tf.experimental.DynamicRaggedShape

The shape of a ragged or dense tensor.

Inherits From: BatchableExtensionType, ExtensionType

tf.experimental.DynamicRaggedShape(
    row_partitions: Sequence[tf.experimental.RowPartition],
    inner_shape: tf.types.experimental.TensorLike,
    dtype: Optional[tf.dtypes.DType] = None,
    validate: bool = False,
    static_inner_shape: ... = None
)

Ragged shapes are encoded using two fields:

  • inner_shape: An integer vector giving the shape of a dense tensor.
  • row_partitions: A list of RowPartition objects, describing how that flat shape should be partitioned to add ragged axes.

If a DynamicRaggedShape is the shape of a RaggedTensor rt, then:

  1. row_partitions = rt._nested_row_partitions (and thus len(row_partitions) > 0)
  2. inner_shape is the shape of rt.flat_values

If a DynamicRaggedShape is the shape of a dense tensor t, then:

  1. row_partitions = []
  2. inner_shape is the shape of t.

Examples:

The following table gives a few examples (where RP(lengths) is short for RowPartition.from_lengths(lengths)):

Row Partitions Inner Shape Example Tensor
[] [2, 3] [[1, 2, 3], [4, 5, 6]]
[RP([2, 0, 3])] [5] [[1, 2], [], [3, 4, 5]]
[RP([2, 1])] [3, 2] [[[1, 2], [3, 4]], [[5, 6]]]
[RP([2, 1]), RP([2, 1, 2])] [5] [[[1, 2], [3]], [[4, 5]]]

row_partitions the row_partitions of the shape.
inner_shape if len(row_partitions) > 0, the shape of the flat_values. Otherwise, the shape of the tensor.
dtype tf.int64, tf.int32, or None representing the preferred dtype.
validate if true, dynamic validation is applied to the shape.
static_inner_shape if len(row_partitions) > 0, the static shape of the flat_values. Otherwise, the static shape of the tensor. Should be convertible to a TensorShape.

dtype The dtype of the shape -- one of tf.int32 or tf.int64.
inner_rank The rank of inner_shape.
inner_shape The inner dimension sizes for this shape.
num_row_partitions The number of row_partitions of the shape.
rank The number of dimensions in this shape, or None if unknown.
row_partitions The row_partitions of the shape.

Child Classes

class Spec

Methods

from_lengths

View source

@classmethod
from_lengths(
    lengths: Sequence[Union[Sequence[int], int]],
    num_row_partitions=None,
    dtype=tf.dtypes.int64
)

Creates a shape with the given lengths and num_row_partitions.

The lengths can either be a nonnegative int or a list of nonnegative ints.

If num_row_partitions is None, then the minimal num_row_partitions is used.

For example, [2, (3, 2)] is the shape of [[0, 0, 0], [0, 0]], and [2, 2] is the shape of [[0, 0], [0, 0]]

This chooses the minimal num_row_partitions required (including zero).

The following table gives a few examples (where RP(lengths) is short for RowPartition.from_lengths(lengths)):

For example:

from_lengths row_partitions inner_shape
[] [] []
[2, (3, 2)] [RP([3, 2])] [5]
[2, 2] [] [2, 2]
[2, (3, 2), 7] [RP([3, 2])] [5, 7]
[2, (2, 2), 3] [RP([2, 2])] [4, 3]
[2, 2, 3] [] [2, 2, 3]
[2, (2, 1), (2, 0, 3)] [RP(2, 1), RP([2, 0, 3])] [5]

If we want the row partitions to end with uniform row partitions, then we can set num_row_partitions.

For example, below URP(3, 12) is RowPartition.from_uniform_row_length(3, 12)

from_lengths num_row_partitions row_partitions inner_shape
[2, (3, 2), 2] 2 [RP([3, 2]), URP(2, 10)] [10]
[2, 2] 1 [URP(2, 4)] [4]
[2, 2, 3] 0 [] [2, 2, 3]
[2, 2, 3] 1 [URP(2, 4)] [4, 3]
[2, 2, 3] 2 [URP(2, 4), URP(3, 12)] [12]

Representing the shapes from init():

from_lengths Tensor Example
[2, 3] [[1, 2, 3], [4, 5, 6]]
[3, (2, 0, 3)] [[1, 2], [], [3, 4, 5]]
[2, (2, 1), 2] [[[1, 2], [3, 4]], [[5, 6]]]
[2, (2, 1), (2, 1, 2)] [[[1, 2], [3]], [[4, 5]]]

Args
lengths the lengths of sublists along each axis.
num_row_partitions the num_row_partitions of the result or None indicating the minimum number of row_partitions.
dtype the dtype of the shape (tf.int32 or tf.int64).

Returns
a new DynamicRaggedShape

from_row_partitions

View source

@classmethod
from_row_partitions(
    row_partitions, dtype=None
)

Create a shape from row_partitions.

Args
row_partitions a nonempty list of RowPartition objects.
dtype the dtype to use, or None to use the row_partitions dtype.

Returns
a DynamicRaggedShape with inner_rank==1.

from_tensor

View source

@classmethod
from_tensor(
    t, dtype=None
)

Constructs a ragged shape for a potentially ragged tensor.

is_uniform

View source

is_uniform(
    axis
)

Returns true if the indicated dimension is uniform.

static_lengths

View source

static_lengths(
    ragged_lengths=True
)

Returns a list of statically known axis lengths.

This represents what values are known. For each row partition, it presents either the uniform row length (if statically known), the list of row lengths, or none if it is not statically known. For the inner shape, if the rank is known, then each dimension is reported if known, and None otherwise. If the rank of the inner shape is not known, then the returned list ends with an ellipsis.

Args
ragged_lengths If false, returns None for all ragged dimensions.

Returns
A Sequence[Union[Sequence[int],int, None]] of lengths, with a possible Ellipsis at the end.

with_dtype

View source

with_dtype(
    dtype
)

Change the dtype of the shape.

__eq__

View source

__eq__(
    other
)

Return self==value.

__getitem__

View source

__getitem__(
    index
)

Returns a dimension or a slice of the shape.

Ragged shapes can have ragged dimensions that depend upon other dimensions. Therefore, if you ask for a dimension that is ragged, this function returns a ValueError. For similar reasons, if a slice is selected that includes a ragged dimension without including the zero dimension, then this fails.

Any slice that does not start at zero will return a shape with num_row_partitions == 0.

Args
index the index: can be an int or a slice.

Raises
IndexError if the index is not in range.
ValueError if the rank is unknown, or a ragged rank is requested incorrectly.

__ne__

View source

__ne__(
    other
)

Return self!=value.