|TensorFlow 1 version||View source on GitHub|
Represents a ragged tensor.
Compat aliases for migration
See Migration guide for more details.
Used in the notebooks
|Used in the guide||Used in the tutorials|
RaggedTensor is a tensor with one or more ragged dimensions, which are
dimensions whose slices may have different lengths. For example, the inner
(column) dimension of
rt=[[3, 1, 4, 1], , [5, 9, 2], , ] is ragged,
since the column slices (
rt[0, :], ...,
rt[4, :]) have different lengths.
Dimensions whose slices all have the same length are called uniform
dimensions. The outermost dimension of a
RaggedTensor is always uniform,
since it consists of a single slice (and so there is no possibility for
differing slice lengths).
The total number of dimensions in a
RaggedTensor is called its rank,
and the number of ragged dimensions in a
RaggedTensor is called its
RaggedTensor's ragged-rank is fixed at graph creation
time: it can't depend on the runtime values of
Tensors, and can't vary
dynamically for different session runs.
Note that the
__init__ constructor is private. Please use one of the
following methods to construct a
Potentially Ragged Tensors
Many ops support both
(see tf.ragged for a
full listing). The term "potentially ragged tensor" may be used to refer to a
tensor that might be either a
Tensor or a
RaggedTensor. The ragged-rank
Tensor is zero.
Documenting RaggedTensor Shapes
When documenting the shape of a RaggedTensor, ragged dimensions can be
indicated by enclosing them in parentheses. For example, the shape of
RaggedTensor that stores the fixed-size word embedding for each
word in a sentence, for each sentence in a batch, could be written as
[num_sentences, (num_words), embedding_size]. The parentheses around
(num_words) indicate that dimension is ragged, and that the length
of each element list in that dimension may vary for each item.
RaggedTensor consists of a concatenated list of values that
are partitioned into variable-length rows. In particular, each
valuestensor, which concatenates the variable-length rows into a flattened list. For example, the
[[3, 1, 4, 1], , [5, 9, 2], , ]is
[3, 1, 4, 1, 5, 9, 2, 6].
row_splitsvector, which indicates how those flattened values are divided into rows. In particular, the values for row
rt[i]are stored in the slice
values=[3, 1, 4, 1, 5, 9, 2, 6],
row_splits=[0, 4, 4, 7, 8, 8]))
<tf.RaggedTensor [[3, 1, 4, 1], , [5, 9, 2], , ]>
Alternative Row-Partitioning Schemes
In addition to
row_splits, ragged tensors provide support for five other
row_lengths: a vector with shape
[nrows], which specifies the length of each row.
value_rowidsis a vector with shape
[nvals], corresponding one-to-one with
values, which specifies each value's row index. In particular, the row
rt[row]consists of the values
nrowsis an integer scalar that specifies the number of rows in the
nrowsis used to indicate trailing empty rows.)
row_starts: a vector with shape
[nrows], which specifies the start offset of each row. Equivalent to
row_limits: a vector with shape
[nrows], which specifies the stop offset of each row. Equivalent to
uniform_row_length: A scalar tensor, specifying the length of every row. This row-partitioning scheme may only be used if all rows have the same length.
Example: The following ragged tensors are equivalent, and all represent the
[[3, 1, 4, 1], , [5, 9, 2], , ].
values = [3, 1, 4, 1, 5, 9, 2, 6]
rt1 = RaggedTensor.from_row_splits(values, row_splits=[0, 4, 4, 7, 8, 8])
rt2 = RaggedTensor.from_row_lengths(values, row_lengths=[4, 0, 3, 1, 0])
rt3 = RaggedTensor.from_value_rowids(
values, value_rowids=[0, 0, 0, 0, 2, 2, 2, 3], nrows=5)
rt4 = RaggedTensor.from_row_starts(values, row_starts=[0, 4, 4, 7, 8])
rt5 = RaggedTensor.from_row_limits(values, row_limits=[4, 4, 7, 8, 8])
Multiple Ragged Dimensions
RaggedTensors with multiple ragged dimensions can be defined by using
RaggedTensor for the
values tensor. Each nested
adds a single ragged dimension.
inner_rt = RaggedTensor.from_row_splits( # =rt1 from above
values=[3, 1, 4, 1, 5, 9, 2, 6], row_splits=[0, 4, 4, 7, 8, 8])
outer_rt = RaggedTensor.from_row_splits(
values=inner_rt, row_splits=[0, 3, 3, 5])
[[[3, 1, 4, 1], , [5, 9, 2]], , [, ]]
The factory function
RaggedTensor.from_nested_row_splits may be used to
RaggedTensor with multiple ragged dimensions directly, by
providing a list of