|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
flat_values=[3, 1, 4, 1, 5, 9, 2, 6],
nested_row_splits=([0, 3, 3, 5], [0, 4, 4, 7, 8, 8])).to_list()
[[[3, 1, 4, 1], , [5, 9, 2]], , [, ]]
Uniform Inner Dimensions
RaggedTensors with uniform inner dimensions can be defined
by using a multidimensional
rt = RaggedTensor.from_row_splits(values=tf.ones([5, 3], tf.int32),
row_splits=[0, 2, 5])
[[[1, 1, 1], [1, 1, 1]],
[[1, 1, 1], [1, 1, 1], [1, 1, 1]]]
(2, None, 3)
Uniform Outer Dimensions
RaggedTensors with uniform outer dimensions can be defined by using
one or more
RaggedTensor with a
tensor. For example, a
RaggedTensor with shape
[2, 2, None] can be
constructed with this method from a
RaggedTensor values with shape
values = tf.ragged.constant([[1, 2, 3], , [5, 6], [7, 8, 9, 10]])
rt6 = tf.RaggedTensor.from_uniform_row_length(values, 2)
<tf.RaggedTensor [[[1, 2, 3], ], [[5, 6], [7, 8, 9, 10]]]>
(2, 2, None)
rt6 only contains one ragged dimension (the innermost
dimension). In contrast, if
from_row_splits is used to construct a similar
RaggedTensor, then that
RaggedTensor will have two ragged dimensions:
rt7 = tf.RaggedTensor.from_row_splits(values, [0, 2, 4])
(2, None, None)
Uniform and ragged outer dimensions may be interleaved, meaning that a
tensor with any combination of ragged and uniform dimensions may be created.
For example, a RaggedTensor
t4 with shape
[3, None, 4, 8, None, 2] could
be constructed as follows:
t0 = tf.zeros([1000, 2]) # Shape: [1000, 2] t1 = RaggedTensor.from_row_lengths(t0, [...]) # [160, None, 2] t2 = RaggedTensor.from_uniform_row_length(t1, 8) # [20, 8, None, 2] t3 = RaggedTensor.from_uniform_row_length(t2, 4) # [5, 4, 8, None, 2] t4 = RaggedTensor.from_row_lengths(t3, [...]) # [3, None, 4, 8, None, 2]
A tuple containing the row_splits for all ragged dimensions.
The number of times the RaggedTensor's flat_values is partitioned.
The row-split indices for this ragged tensor's
The statically known shape of this ragged tensor.
The length of each row in this ragged tensor, or None if rows are ragged.
A RaggedTensor's rows are only considered to be uniform (i.e. non-ragged) if it can be determined statically (at graph construction time) that the rows all have the same length.
The concatenated rows for this ragged tensor.
bounding_shape( axis=None, name=None, out_type=None )
Returns the tight bounding box shape for this
||An integer scalar or vector indicating which axes to return the bounding box for. If not specified, then the full bounding box is returned.|
||A name prefix for the returned tensor (optional).|
rt = tf.ragged.constant([[1, 2, 3, 4], , , [6, 7, 8, 9], ])
from_nested_row_lengths( flat_values, nested_row_lengths, name=None, validate=True )
RaggedTensor from a nested list of
result = flat_values for row_lengths in reversed(nested_row_lengths): result = from_row_lengths(result, row_lengths)
||A potentially ragged tensor.|
A list of 1-D integer tensors. The
||A name prefix for the RaggedTensor (optional).|
||If true, then use assertions to check that the arguments for|