View source on GitHub |
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 ofRowPartition
objects, describing how that flat shape should be partitioned to add ragged axes.
If a DynamicRaggedShape is the shape of a RaggedTensor rt, then:
- row_partitions = rt._nested_row_partitions (and thus len(row_partitions) > 0)
- inner_shape is the shape of rt.flat_values
If a DynamicRaggedShape is the shape of a dense tensor t, then:
- row_partitions = []
- 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]]] |
Child Classes
Methods
from_lengths
@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
@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
@classmethod
from_tensor( t, dtype=None )
Constructs a ragged shape for a potentially ragged tensor.
is_uniform
is_uniform(
axis
)
Returns true if the indicated dimension is uniform.
static_lengths
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
with_dtype(
dtype
)
Change the dtype of the shape.
__eq__
__eq__(
other
)
Return self==value.
__getitem__
__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__
__ne__(
other
)
Return self!=value.