tf.RaggedTensor

View source on GitHub

Represents a ragged tensor.

tf.RaggedTensor(
    values, row_splits, cached_row_lengths=None, cached_value_rowids=None,
    cached_nrows=None, internal=False, uniform_row_length=None
)

A 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], [6], []] 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 ragged-rank. A 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 Tensors and 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 a 3-D 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.

Component Tensors

Internally, a RaggedTensor consists of a concatenated list of values that are partitioned into variable-length rows. In particular, each RaggedTensor consists of:

Example:

>>> print(tf.RaggedTensor.from_row_splits(
...       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], [6], []]>

Alternative Row-Partitioning Schemes

In addition to row_splits, ragged tensors provide support for four other row-partitioning schemes:

Example: The following ragged tensors are equivalent, and all represent the nested list [[3, 1, 4, 1], [], [5, 9, 2], [6], []].

>>> 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 a nested RaggedTensor for the values tensor. Each nested RaggedTensor 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])
>>> print(outer_rt.to_list())
[[[3, 1, 4, 1], [], [5, 9, 2]], [], [[6], []]]
>>> print(outer_rt.ragged_rank)
2

The factory function RaggedTensor.from_nested_row_splits may be used to construct a RaggedTensor with multiple ragged dimensions directly, by providing a list of row_splits tensors:

>>> RaggedTensor.from_nested_row_splits(
...     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]], [], [[6], []]]

Uniform Inner Dimensions

RaggedTensors with uniform inner dimensions can be defined by using a multidimensional Tensor for values.

>>> rt = RaggedTensor.from_row_splits(values=tf.ones([5, 3], tf.int32),
...                                   row_splits=[0, 2, 5])
>>> print(rt.to_list())
[[[1, 1, 1], [1, 1, 1]],
 [[1, 1, 1], [1, 1, 1], [1, 1, 1]]]
>>> print(rt.shape)
(2, None, 3)

Uniform Outer Dimensions

RaggedTensors with uniform outer dimensions can be defined by using one or more RaggedTensor with a uniform_row_length row-partitioning tensor. For example, a RaggedTensor with shape [2, 2, None] can be constructed with this method from a RaggedTensor values with shape [4, None]:

>>> values = tf.ragged.constant([[1, 2, 3], [4], [5, 6], [7, 8, 9, 10]])
>>> print(values.shape)
(4, None)
>>> rt6 = tf.RaggedTensor.from_uniform_row_length(values, 2)
>>> print(rt6)
<tf.RaggedTensor [[[1, 2, 3], [4]], [[5, 6], [7, 8, 9, 10]]]>
>>> print(rt6.shape)
(2, 2, None)

Note that 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])
>>> print(rt7.shape)
(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]

Args:

Attributes:

Raises:

Methods

__abs__

View source

__abs__(
    x, name=None
)

Computes the absolute value of a tensor.

Given a tensor of integer or floating-point values, this operation returns a tensor of the same type, where each element contains the absolute value of the corresponding element in the input.

Given a tensor x of complex numbers, this operation returns a tensor of type float32 or float64 that is the absolute value of each element in x. All elements in x must be complex numbers of the form \(a + bj\). The absolute value is computed as \( \sqrt{a2 + b2}\). For example: python x = tf.constant([[-2.25 + 4.75j], [-3.25 + 5.75j]]) tf.abs(x) # [5.25594902, 6.60492229]

Args:

Returns:

A Tensor or SparseTensor the same size, type, and sparsity as x with absolute values. Note, for complex64 or complex128 input, the returned Tensor will be of type float32 or float64, respectively.

If x is a SparseTensor, returns SparseTensor(x.indices, tf.math.abs(x.values, ...), x.dense_shape)

__add__

__add__(
    x, y, name=None
)

Returns x + y element-wise.

NOTE: math.add supports broadcasting. AddN does not. More about broadcasting here

Args:

Returns:

A Tensor. Has the same type as x.

__and__

__and__(
    x, y, name=None
)

Returns the truth value of x AND y element-wise.

NOTE: math.logical_and supports broadcasting. More about broadcasting here

Args:

Returns:

A Tensor of type bool.

__bool__

View source

__bool__(
    _
)

Dummy method to prevent a RaggedTensor from being used as a Python bool.

__div__

View source

__div__(
    x, y, name=None
)

Divides x / y elementwise (using Python 2 division operator semantics). (deprecated)

Warning: THIS FUNCTION IS DEPRECATED. It will be removed in a future version. Instructions for updating: Deprecated in favor of operator or tf.math.divide.

NOTE: Prefer using the Tensor division operator or tf.divide which obey Python 3 division operator semantics.

This function divides x and y, forcing Python 2 semantics. That is, if x and y are both integers then the result will be an integer. This is in contrast to Python 3, where division with / is always a float while division with // is always an integer.

Args:

Returns:

x / y returns the quotient of x and y.

__floordiv__

View source

__floordiv__(
    x, y, name=None
)

Divides x / y elementwise, rounding toward the most negative integer.

The same as tf.compat.v1.div(x,y) for integers, but uses tf.floor(tf.compat.v1.div(x,y)) for floating point arguments so that the result is always an integer (though possibly an integer represented as floating point). This op is generated by x // y floor division in Python 3 and in Python 2.7 with from __future__ import division.

x and y must have the same type, and the result will have the same type as well.

Args:

Returns:

x / y rounded down.

Raises:

__ge__

__ge__(
    x, y, name=None
)

Returns the truth value of (x >= y) element-wise.

NOTE: math.greater_equal supports broadcasting. More about broadcasting here

Example:

x = tf.constant([5, 4, 6, 7])
y = tf.constant([5, 2, 5, 10])
tf.math.greater_equal(x, y) ==> [True, True, True, False]

x = tf.constant([5, 4, 6, 7])
y = tf.constant([5])
tf.math.greater_equal(x, y) ==> [True, False, True, True]

Args:

Returns:

A Tensor of type bool.

__getitem__

View source

__getitem__(
    key
)

Returns the specified piece of this RaggedTensor.

Supports multidimensional indexing and slicing, with one restriction: indexing into a ragged inner dimension is not allowed. This case is problematic because the indicated value may exist in some rows but not others. In such cases, it's not obvious whether we should (1) report an IndexError; (2) use a default value; or (3) skip that value and return a tensor with fewer rows than we started with. Following the guiding principles of Python ("In the face of ambiguity, refuse the temptation to guess"), we simply disallow this operation.

Any dimensions added by array_ops.newaxis will be ragged if the following dimension is ragged.

Args:

Returns:

A Tensor or RaggedTensor object. Values that include at least one ragged dimension are returned as RaggedTensor. Values that include no ragged dimensions are returned as Tensor. See above for examples of expressions that return Tensors vs RaggedTensors.

Raises:

Examples:

>>> # A 2-D ragged tensor with 1 ragged dimension.
>>> rt = tf.ragged.constant([['a', 'b', 'c'], ['d', 'e'], ['f'], ['g']])
>>> rt[0].numpy()                 # First row (1-D `Tensor`)
array([b'a', b'b', b'c'], dtype=object)
>>> rt[:3].to_list()              # First three rows (2-D RaggedTensor)
[[b'a', b'b', b'c'], [b'd', b'e'], [b'f']]
>>> rt[3, 0].numpy()              # 1st element of 4th row (scalar)
b'g'
>>> # A 3-D ragged tensor with 2 ragged dimensions.
>>> rt = tf.ragged.constant([[[1, 2, 3], [4]],
...                          [[5], [], [6]],
...                          [[7]],
...                          [[8, 9], [10]]])
>>> rt[1].to_list()               # Second row (2-D RaggedTensor)
[[5], [], [6]]
>>> rt[3, 0].numpy()              # First element of fourth row (1-D Tensor)
array([8, 9], dtype=int32)
>>> rt[:, 1:3].to_list()          # Items 1-3 of each row (3-D RaggedTensor)
[[[4]], [[], [6]], [], [[10]]]
>>> rt[:, -1:].to_list()          # Last item of each row (3-D RaggedTensor)
[[[4]], [[6]], [[7]], [[10]]]

__gt__

__gt__(
    x, y, name=None
)

Returns the truth value of (x > y) element-wise.

NOTE: math.greater supports broadcasting. More about broadcasting here

Example:

x = tf.constant([5, 4, 6])
y = tf.constant([5, 2, 5])
tf.math.greater(x, y) ==> [False, True, True]

x = tf.constant([5, 4, 6])
y = tf.constant([5])
tf.math.greater(x, y) ==> [False, False, True]

Args:

Returns:

A Tensor of type bool.

__invert__

__invert__(
    x, name=None
)

Returns the truth value of NOT x element-wise.

Args:

Returns:

A Tensor of type bool.

__le__

__le__(
    x, y, name=None
)

Returns the truth value of (x <= y) element-wise.

NOTE: math.less_equal supports broadcasting. More about broadcasting here

Example:

x = tf.constant([5, 4, 6])
y = tf.constant([5])
tf.math.less_equal(x, y) ==> [True, True, False]

x = tf.constant([5, 4, 6])
y = tf.constant([5, 6, 6])
tf.math.less_equal(x, y) ==> [True, True, True]

Args:

Returns:

A Tensor of type bool.

__lt__

__lt__(
    x, y, name=None
)

Returns the truth value of (x < y) element-wise.

NOTE: math.less supports broadcasting. More about broadcasting here

Example:

x = tf.constant([5, 4, 6])
y = tf.constant([5])
tf.math.less(x, y) ==> [False, True, False]

x = tf.constant([5, 4, 6])
y = tf.constant([5, 6, 7])
tf.math.less(x, y) ==> [False, True, True]

Args:

Returns:

A Tensor of type bool.

__mod__

__mod__(
    x, y, name=None
)

Returns element-wise remainder of division. When x < 0 xor y < 0 is

true, this follows Python semantics in that the result here is consistent with a flooring divide. E.g. floor(x / y) * y + mod(x, y) = x.

NOTE: math.floormod supports broadcasting. More about broadcasting here

Args:

Returns:

A Tensor. Has the same type as x.

__mul__

View source

__mul__(
    x, y, name=None
)

Returns x * y element-wise.

NOTE: tf.multiply supports broadcasting. More about broadcasting here

Args:

Returns:

A Tensor. Has the same type as x.

__neg__

__neg__(
    x, name=None
)

Computes numerical negative value element-wise.

I.e., \(y = -x\).

Args:

Returns:

A Tensor. Has the same type as x.

If x is a SparseTensor, returns SparseTensor(x.indices, tf.math.negative(x.values, ...), x.dense_shape)

__nonzero__

View source

__nonzero__(
    _
)

Dummy method to prevent a RaggedTensor from being used as a Python bool.

__or__

__or__(
    x, y, name=None
)

Returns the truth value of x OR y element-wise.

NOTE: math.logical_or supports broadcasting. More about broadcasting here

Args:

Returns:

A Tensor of type bool.

__pow__

View source

__pow__(
    x, y, name=None
)

Computes the power of one value to another.

Given a tensor x and a tensor y, this operation computes \(xy\) for corresponding elements in x and y. For example:

x = tf.constant([[2, 2], [3, 3]])
y = tf.constant([[8, 16], [2, 3]])
tf.pow(x, y)  # [[256, 65536], [9, 27]]

Args:

Returns:

A Tensor.

__radd__

__radd__(
    x, y, name=None
)

Returns x + y element-wise.

NOTE: math.add supports broadcasting. AddN does not. More about broadcasting here

Args:

Returns:

A Tensor. Has the same type as x.

__rand__

__rand__(
    x, y, name=None
)

Returns the truth value of x AND y element-wise.

NOTE: math.logical_and supports broadcasting. More about broadcasting here

Args:

Returns:

A Tensor of type bool.

__rdiv__

View source

__rdiv__(
    x, y, name=None
)

Divides x / y elementwise (using Python 2 division operator semantics). (deprecated)

Warning: THIS FUNCTION IS DEPRECATED. It will be removed in a future version. Instructions for updating: Deprecated in favor of operator or tf.math.divide.

NOTE: Prefer using the Tensor division operator or tf.divide which obey Python 3 division operator semantics.

This function divides x and y, forcing Python 2 semantics. That is, if x and y are both integers then the result will be an integer. This is in contrast to Python 3, where division with / is always a float while division with // is always an integer.

Args:

Returns:

x / y returns the quotient of x and y.

__rfloordiv__

View source

__rfloordiv__(
    x, y, name=None
)

Divides x / y elementwise, rounding toward the most negative integer.

The same as tf.compat.v1.div(x,y) for integers, but uses tf.floor(tf.compat.v1.div(x,y)) for floating point arguments so that the result is always an integer (though possibly an integer represented as floating point). This op is generated by x // y floor division in Python 3 and in Python 2.7 with from __future__ import division.

x and y must have the same type, and the result will have the same type as well.

Args:

Returns:

x / y rounded down.

Raises:

__rmod__

__rmod__(
    x, y, name=None
)

Returns element-wise remainder of division. When x < 0 xor y < 0 is

true, this follows Python semantics in that the result here is consistent with a flooring divide. E.g. floor(x / y) * y + mod(x, y) = x.

NOTE: math.floormod supports broadcasting. More about broadcasting here

Args:

Returns:

A Tensor. Has the same type as x.

__rmul__

View source

__rmul__(
    x, y, name=None
)

Returns x * y element-wise.

NOTE: tf.multiply supports broadcasting. More about broadcasting here

Args:

Returns:

A Tensor. Has the same type as x.

__ror__

__ror__(
    x, y, name=None
)

Returns the truth value of x OR y element-wise.

NOTE: math.logical_or supports broadcasting. More about broadcasting here

Args:

Returns:

A Tensor of type bool.

__rpow__

View source

__rpow__(
    x, y, name=None
)

Computes the power of one value to another.

Given a tensor x and a tensor y, this operation computes \(xy\) for corresponding elements in x and y. For example:

x = tf.constant([[2, 2], [3, 3]])
y = tf.constant([[8, 16], [2, 3]])
tf.pow(x, y)  # [[256, 65536], [9, 27]]

Args:

Returns:

A Tensor.

__rsub__

View source

__rsub__(
    x, y, name=None
)

Returns x - y element-wise.

NOTE: Subtract supports broadcasting. More about broadcasting here

Args:

Returns:

A Tensor. Has the same type as x.

__rtruediv__

View source

__rtruediv__(
    x, y, name=None
)

Divides x / y elementwise (using Python 3 division operator semantics).

NOTE: Prefer using the Tensor operator or tf.divide which obey Python division operator semantics.

This function forces Python 3 division operator semantics where all integer arguments are cast to floating types first. This op is generated by normal x / y division in Python 3 and in Python 2.7 with from __future__ import division. If you want integer division that rounds down, use x // y or tf.math.floordiv.

x and y must have the same numeric type. If the inputs are floating point, the output will have the same type. If the inputs are integral, the inputs are cast to float32 for int8 and int16 and float64 for int32 and int64 (matching the behavior of Numpy).

Args:

Returns:

x / y evaluated in floating point.

Raises:

__rxor__

View source

__rxor__(
    x, y, name='LogicalXor'
)

Logical XOR function.

x ^ y = (x | y) & ~(x & y)

Inputs are tensor and if the tensors contains more than one element, an element-wise logical XOR is computed.

Usage:

x = tf.constant([False, False, True, True], dtype = tf.bool)
y = tf.constant([False, True, False, True], dtype = tf.bool)
z = tf.logical_xor(x, y, name="LogicalXor")
#  here z = [False  True  True False]

Args:

Returns:

A Tensor of type bool with the same size as that of x or y.

__sub__

View source

__sub__(
    x, y, name=None
)

Returns x - y element-wise.

NOTE: Subtract supports broadcasting. More about broadcasting here

Args:

Returns:

A Tensor. Has the same type as x.

__truediv__

View source

__truediv__(
    x, y, name=None
)

Divides x / y elementwise (using Python 3 division operator semantics).

NOTE: Prefer using the Tensor operator or tf.divide which obey Python division operator semantics.

This function forces Python 3 division operator semantics where all integer arguments are cast to floating types first. This op is generated by normal x / y division in Python 3 and in Python 2.7 with from __future__ import division. If you want integer division that rounds down, use x // y or tf.math.floordiv.

x and y must have the same numeric type. If the inputs are floating point, the output will have the same type. If the inputs are integral, the inputs are cast to float32 for int8 and int16 and float64 for int32 and int64 (matching the behavior of Numpy).

Args:

Returns:

x / y evaluated in floating point.

Raises:

__xor__

View source

__xor__(
    x, y, name='LogicalXor'
)

Logical XOR function.

x ^ y = (x | y) & ~(x & y)

Inputs are tensor and if the tensors contains more than one element, an element-wise logical XOR is computed.

Usage:

x = tf.constant([False, False, True, True], dtype = tf.bool)
y = tf.constant([False, True, False, True], dtype = tf.bool)
z = tf.logical_xor(x, y, name="LogicalXor")
#  here z = [False  True  True False]

Args:

Returns:

A Tensor of type bool with the same size as that of x or y.

bounding_shape

View source

bounding_shape(
    axis=None, name=None, out_type=None
)

Returns the tight bounding box shape for this RaggedTensor.

Args:

Returns:

An integer Tensor (dtype=self.row_splits.dtype). If axis is not specified, then output is a vector with output.shape=[self.shape.ndims]. If axis is a scalar, then the output is a scalar. If axis is a vector, then output is a vector, where output[i] is the bounding size for dimension axis[i].

Example:

>>> rt = tf.ragged.constant([[1, 2, 3, 4], [5], [], [6, 7, 8, 9], [10]])
>>> rt.bounding_shape().numpy()
array([5, 4])

consumers

View source

consumers()

from_nested_row_lengths

View source

@classmethod
from_nested_row_lengths(
    flat_values, nested_row_lengths, name=None, validate=True
)

Creates a RaggedTensor from a nested list of row_lengths tensors.

Equivalent to:

result = flat_values
for row_lengths in reversed(nested_row_lengths):
  result = from_row_lengths(result, row_lengths)

Args:

Returns:

A RaggedTensor (or flat_values if nested_row_lengths is empty).

from_nested_row_splits

View source

@classmethod
from_nested_row_splits(
    flat_values, nested_row_splits, name=None, validate=True
)

Creates a RaggedTensor from a nested list of row_splits tensors.

Equivalent to:

result = flat_values
for row_splits in reversed(nested_row_splits):
  result = from_row_splits(result, row_splits)

Args:

Returns:

A RaggedTensor (or flat_values if nested_row_splits is empty).

from_nested_value_rowids

View source

@classmethod
from_nested_value_rowids(
    flat_values, nested_value_rowids, nested_nrows=None, name=None, validate=True
)

Creates a RaggedTensor from a nested list of value_rowids tensors.

Equivalent to:

result = flat_values
for (rowids, nrows) in reversed(zip(nested_value_rowids, nested_nrows)):
  result = from_value_rowids(result, rowids, nrows)

Args:

Returns:

A RaggedTensor (or flat_values if nested_value_rowids is empty).

Raises:

from_row_lengths

View source

@classmethod
from_row_lengths(
    values, row_lengths, name=None, validate=True
)

Creates a RaggedTensor with rows partitioned by row_lengths.

The returned RaggedTensor corresponds with the python list defined by:

result = [[values.pop(0) for i in range(length)]
          for length in row_lengths]

Args:

Returns:

A RaggedTensor. result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.

Example:

>>> print(tf.RaggedTensor.from_row_lengths(
...     values=[3, 1, 4, 1, 5, 9, 2, 6],
...     row_lengths=[4, 0, 3, 1, 0]))
<tf.RaggedTensor [[3, 1, 4, 1], [], [5, 9, 2], [6], []]>

from_row_limits

View source

@classmethod
from_row_limits(
    values, row_limits, name=None, validate=True
)

Creates a RaggedTensor with rows partitioned by row_limits.

Equivalent to: from_row_splits(values, concat([0, row_limits])).

Args:

Returns:

A RaggedTensor. result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.

Example:

>>> print(tf.RaggedTensor.from_row_limits(
...     values=[3, 1, 4, 1, 5, 9, 2, 6],
...     row_limits=[4, 4, 7, 8, 8]))
<tf.RaggedTensor [[3, 1, 4, 1], [], [5, 9, 2], [6], []]>

from_row_splits

View source

@classmethod
from_row_splits(
    values, row_splits, name=None, validate=True
)

Creates a RaggedTensor with rows partitioned by row_splits.

The returned RaggedTensor corresponds with the python list defined by:

result = [values[row_splits[i]:row_splits[i + 1]]
          for i in range(len(row_splits) - 1)]

Args:

Returns:

A RaggedTensor. result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.

Raises:

Example:

>>> print(tf.RaggedTensor.from_row_splits(
...     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], [6], []]>

from_row_starts

View source

@classmethod
from_row_starts(
    values, row_starts, name=None, validate=True
)

Creates a RaggedTensor with rows partitioned by row_starts.

Equivalent to: from_row_splits(values, concat([row_starts, nvals])).

Args:

Returns:

A RaggedTensor. result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.

Example:

>>> print(tf.RaggedTensor.from_row_starts(
...     values=[3, 1, 4, 1, 5, 9, 2, 6],
...     row_starts=[0, 4, 4, 7, 8]))
<tf.RaggedTensor [[3, 1, 4, 1], [], [5, 9, 2], [6], []]>

from_sparse

View source

@classmethod
from_sparse(
    st_input, name=None, row_splits_dtype=tf.dtypes.int64
)

Converts a 2D tf.SparseTensor to a RaggedTensor.

Each row of the output RaggedTensor will contain the explicit values from the same row in st_input. st_input must be ragged-right. If not it is not ragged-right, then an error will be generated.

Example:

>>> st = tf.SparseTensor(indices=[[0, 0], [0, 1], [0, 2], [1, 0], [3, 0]],
...                      values=[1, 2, 3, 4, 5],
...                      dense_shape=[4, 3])
>>> tf.RaggedTensor.from_sparse(st).to_list()
[[1, 2, 3], [4], [], [5]]

Currently, only two-dimensional SparseTensors are supported.

Args:

Returns:

A RaggedTensor with the same values as st_input. output.ragged_rank = rank(st_input) - 1. output.shape = [st_input.dense_shape[0], None].

Raises:

from_tensor

View source

@classmethod
from_tensor(
    tensor, lengths=None, padding=None, ragged_rank=1, name=None,
    row_splits_dtype=tf.dtypes.int64
)

Converts a tf.Tensor into a RaggedTensor.

The set of absent/default values may be specified using a vector of lengths or a padding value (but not both). If lengths is specified, then the output tensor will satisfy output[row] = tensor[row][:lengths[row]]. If 'lengths' is a list of lists or tuple of lists, those lists will be used as nested row lengths. If padding is specified, then any row suffix consisting entirely of padding will be excluded from the returned RaggedTensor. If neither lengths nor padding is specified, then the returned RaggedTensor will have no absent/default values.

Examples:

>>> dt = tf.constant([[5, 7, 0], [0, 3, 0], [6, 0, 0]])
>>> tf.RaggedTensor.from_tensor(dt)
<tf.RaggedTensor [[5, 7, 0], [0, 3, 0], [6, 0, 0]]>
>>> tf.RaggedTensor.from_tensor(dt, lengths=[1, 0, 3])
<tf.RaggedTensor [[5], [], [6, 0, 0]]>
>>> tf.RaggedTensor.from_tensor(dt, padding=0)
<tf.RaggedTensor [[5, 7], [0, 3], [6]]>
>>> dt = tf.constant([[[5, 0], [7, 0], [0, 0]],
...                   [[0, 0], [3, 0], [0, 0]],
...                   [[6, 0], [0, 0], [0, 0]]])
>>> tf.RaggedTensor.from_tensor(dt, lengths=([2, 0, 3], [1, 1, 2, 0, 1]))
<tf.RaggedTensor [[[5], [7]], [], [[6, 0], [], [0]]]>

Args:

Returns:

A RaggedTensor with the specified ragged_rank. The shape of the returned ragged tensor is compatible with the shape of tensor.

Raises:

from_uniform_row_length

View source

@classmethod
from_uniform_row_length(
    values, uniform_row_length, nrows=None, validate=True, name=None
)

Creates a RaggedTensor with rows partitioned by uniform_row_length.

This method can be used to create RaggedTensors with multiple uniform outer dimensions. For example, a RaggedTensor with shape [2, 2, None] can be constructed with this method from a RaggedTensor values with shape [4, None]:

>>> values = tf.ragged.constant([[1, 2, 3], [4], [5, 6], [7, 8, 9, 10]])
>>> print(values.shape)
(4, None)
>>> rt1 = tf.RaggedTensor.from_uniform_row_length(values, 2)
>>> print(rt1)
<tf.RaggedTensor [[[1, 2, 3], [4]], [[5, 6], [7, 8, 9, 10]]]>
>>> print(rt1.shape)
(2, 2, None)

Note that rt1 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:

>>> rt2 = tf.RaggedTensor.from_row_splits(values, [0, 2, 4])
>>> print(rt2.shape)
(2, None, None)

Args:

Returns:

A RaggedTensor that corresponds with the python list defined by:

result = [[values.pop(0) for i in range(uniform_row_length)]
          for _ in range(nrows)]

result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.

from_value_rowids

View source

@classmethod
from_value_rowids(
    values, value_rowids, nrows=None, name=None, validate=True
)

Creates a RaggedTensor with rows partitioned by value_rowids.

The returned RaggedTensor corresponds with the python list defined by:

result = [[values[i] for i in range(len(values)) if value_rowids[i] == row]
          for row in range(nrows)]

Args:

Returns:

A RaggedTensor. result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.

Raises:

Example:

>>> print(tf.RaggedTensor.from_value_rowids(
...     values=[3, 1, 4, 1, 5, 9, 2, 6],
...     value_rowids=[0, 0, 0, 0, 2, 2, 2, 3],
...     nrows=5))
<tf.RaggedTensor [[3, 1, 4, 1], [], [5, 9, 2], [6], []]>

merge_dims

View source

merge_dims(
    outer_axis, inner_axis
)

Merges outer_axis...inner_axis into a single dimension.

Returns a copy of this RaggedTensor with the specified range of dimensions flattened into a single dimension, with elements in row-major order.

Examples:

>>> rt = tf.ragged.constant([[[1, 2], [3]], [[4, 5, 6]]])
>>> print(rt.merge_dims(0, 1))
<tf.RaggedTensor [[1, 2], [3], [4, 5, 6]]>
>>> print(rt.merge_dims(1, 2))
<tf.RaggedTensor [[1, 2, 3], [4, 5, 6]]>
>>> print(rt.merge_dims(0, 2))
tf.Tensor([1 2 3 4 5 6], shape=(6,), dtype=int32)

To mimic the behavior of np.flatten (which flattens all dimensions), use rt.merge_dims(0, -1). To mimic the behavior oftf.layers.Flatten(which flattens all dimensions except the outermost batch dimension), use rt.merge_dims(1, -1)`.

Args:

Returns:

A copy of this tensor, with the specified dimensions merged into a single dimension. The shape of the returned tensor will be self.shape[:outer_axis] + [N] + self.shape[inner_axis + 1:], where N is the total number of slices in the merged dimensions.

nested_row_lengths

View source

nested_row_lengths(
    name=None
)

Returns a tuple containing the row_lengths for all ragged dimensions.

rt.nested_row_lengths() is a tuple containing the row_lengths tensors for all ragged dimensions in rt, ordered from outermost to innermost.

Args:

Returns:

A tuple of 1-D integer Tensors. The length of the tuple is equal to self.ragged_rank.

nested_value_rowids

View source

nested_value_rowids(
    name=None
)

Returns a tuple containing the value_rowids for all ragged dimensions.

rt.nested_value_rowids is a tuple containing the value_rowids tensors for all ragged dimensions in rt, ordered from outermost to innermost. In particular, rt.nested_value_rowids = (rt.value_rowids(),) + value_ids where:

* `value_ids = ()` if `rt.values` is a `Tensor`.
* `value_ids = rt.values.nested_value_rowids` otherwise.

Args:

Returns:

A tuple of 1-D integer Tensors.

Example:

>>> rt = tf.ragged.constant(
...     [[[[3, 1, 4, 1], [], [5, 9, 2]], [], [[6], []]]])
>>> for i, ids in enumerate(rt.nested_value_rowids()):
...   print('row ids for dimension %d: %s' % (i+1, ids.numpy()))
row ids for dimension 1: [0 0 0]
row ids for dimension 2: [0 0 0 2 2]
row ids for dimension 3: [0 0 0 0 2 2 2 3]

nrows

View source

nrows(
    out_type=None, name=None
)

Returns the number of rows in this ragged tensor.

I.e., the size of the outermost dimension of the tensor.

Args:

Returns:

A scalar Tensor with dtype out_type.

Example:

>>> rt = tf.ragged.constant([[3, 1, 4, 1], [], [5, 9, 2], [6], []])
>>> print(rt.nrows())  # rt has 5 rows.
tf.Tensor(5, shape=(), dtype=int64)

row_lengths

View source

row_lengths(
    axis=1, name=None
)

Returns the lengths of the rows in this ragged tensor.

rt.row_lengths()[i] indicates the number of values in the ith row of rt.

Args:

Returns:

A potentially ragged integer Tensor with shape self.shape[:axis].

Raises:

Example:

>>> rt = tf.ragged.constant(
...     [[[3, 1, 4], [1]], [], [[5, 9], [2]], [[6]], []])
>>> print(rt.row_lengths())  # lengths of rows in rt
tf.Tensor([2 0 2 1 0], shape=(5,), dtype=int64)
>>> print(rt.row_lengths(axis=2))  # lengths of axis=2 rows.
<tf.RaggedTensor [[3, 1], [], [2, 1], [1], []]>

row_limits

View source

row_limits(
    name=None
)

Returns the limit indices for rows in this ragged tensor.

These indices specify where the values for each row end in self.values. rt.row_limits(self) is equal to rt.row_splits[:-1].

Args:

Returns:

A 1-D integer Tensor with shape [nrows]. The returned tensor is nonnegative, and is sorted in ascending order.

Example:

>>> rt = tf.ragged.constant([[3, 1, 4, 1], [], [5, 9, 2], [6], []])
>>> print(rt.values)
tf.Tensor([3 1 4 1 5 9 2 6], shape=(8,), dtype=int32)
>>> print(rt.row_limits())  # indices of row limits in rt.values
tf.Tensor([4 4 7 8 8], shape=(5,), dtype=int64)

row_starts

View source

row_starts(
    name=None
)

Returns the start indices for rows in this ragged tensor.

These indices specify where the values for each row begin in self.values. rt.row_starts() is equal to rt.row_splits[:-1].

Args:

Returns:

A 1-D integer Tensor with shape [nrows]. The returned tensor is nonnegative, and is sorted in ascending order.

Example:

>>> rt = tf.ragged.constant([[3, 1, 4, 1], [], [5, 9, 2], [6], []])
>>> print(rt.values)
tf.Tensor([3 1 4 1 5 9 2 6], shape=(8,), dtype=int32)
>>> print(rt.row_starts())  # indices of row starts in rt.values
tf.Tensor([0 4 4 7 8], shape=(5,), dtype=int64)

to_list

View source

to_list()

Returns a nested Python list with the values for this RaggedTensor.

Requires that rt was constructed in eager execution mode.

Returns:

A nested Python list.

to_sparse

View source

to_sparse(
    name=None
)

Converts this RaggedTensor into a tf.SparseTensor.

Example:

>>> rt = tf.ragged.constant([[1, 2, 3], [4], [], [5, 6]])
>>> print(rt.to_sparse())
SparseTensor(indices=tf.Tensor(
                 [[0 0] [0 1] [0 2] [1 0] [3 0] [3 1]],
                 shape=(6, 2), dtype=int64),
             values=tf.Tensor([1 2 3 4 5 6], shape=(6,), dtype=int32),
             dense_shape=tf.Tensor([4 3], shape=(2,), dtype=int64))

Args:

Returns:

A SparseTensor with the same values as self.

to_tensor

View source

to_tensor(
    default_value=None, name=None, shape=None
)

Converts this RaggedTensor into a tf.Tensor.

If shape is specified, then the result is padded and/or truncated to the specified shape.

Examples:

>>> rt = tf.ragged.constant([[9, 8, 7], [], [6, 5], [4]])
>>> print(rt.to_tensor())
tf.Tensor(
    [[9 8 7] [0 0 0] [6 5 0] [4 0 0]], shape=(4, 3), dtype=int32)
>>> print(rt.to_tensor(shape=[5, 2]))
tf.Tensor(
    [[9 8] [0 0] [6 5] [4 0] [0 0]], shape=(5, 2), dtype=int32)

Args:

Returns:

A Tensor with shape ragged.bounding_shape(self) and the values specified by the non-empty values in self. Empty values are assigned default_value.

value_rowids

View source

value_rowids(
    name=None
)

Returns the row indices for the values in this ragged tensor.

rt.value_rowids() corresponds one-to-one with the outermost dimension of rt.values, and specifies the row containing each value. In particular, the row rt[row] consists of the values rt.values[j] where rt.value_rowids()[j] == row.

Args:

Returns:

A 1-D integer Tensor with shape self.values.shape[:1]. The returned tensor is nonnegative, and is sorted in ascending order.

Example:

>>> rt = tf.ragged.constant([[3, 1, 4, 1], [], [5, 9, 2], [6], []])
>>> print(rt.values)
tf.Tensor([3 1 4 1 5 9 2 6], shape=(8,), dtype=int32)
>>> print(rt.value_rowids())  # corresponds 1:1 with rt.values
tf.Tensor([0 0 0 0 2 2 2 3], shape=(8,), dtype=int64)

with_flat_values

View source

with_flat_values(
    new_values
)

Returns a copy of self with flat_values replaced by new_value.

Preserves cached row-partitioning tensors such as self.cached_nrows and self.cached_value_rowids if they have values.

Args:

Returns:

A RaggedTensor. result.rank = self.ragged_rank + new_values.rank. result.ragged_rank = self.ragged_rank + new_values.ragged_rank.

with_row_splits_dtype

View source

with_row_splits_dtype(
    dtype
)

Returns a copy of this RaggedTensor with the given row_splits dtype.

For RaggedTensors with multiple ragged dimensions, the row_splits for all nested RaggedTensor objects are cast to the given dtype.

Args:

Returns:

A copy of this RaggedTensor, with the row_splits cast to the given type.

with_values

View source

with_values(
    new_values
)

Returns a copy of self with values replaced by new_value.

Preserves cached row-partitioning tensors such as self.cached_nrows and self.cached_value_rowids if they have values.

Args:

Returns:

A RaggedTensor. result.rank = 1 + new_values.rank. result.ragged_rank = 1 + new_values.ragged_rank