|TensorFlow 1 version||View source on GitHub|
Represents a ragged tensor.
Compat aliases for migration
See Migration guide for more details.
tf.RaggedTensor( values, row_partition, internal=False )
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.
Potentially Ragged Tensors
Many ops support both
RaggedTensors. 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 of a
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()