tf.experimental.RowPartition

Разбиение последовательности значений на смежные подпоследовательности («строки»).

tf.experimental.RowPartition(
    row_splits,
    row_lengths=None,
    value_rowids=None,
    nrows=None,
    uniform_row_length=None,
    nvals=None,
    internal=False
)

Объект RowPartition описывает, как последовательность из nvals элементов должна быть разделена на nrows смежных подпоследовательностей («строк»). Например, RowPartition можно использовать для разбиения вектора [1, 2, 3, 4, 5] на подпоследовательности [[1, 2], [3], [], [4, 5]]. Обратите внимание, что RowPartition хранит информацию о том, как значения разделены, но не включает сами раздёленные значения. tf.RaggedTensor используется для объединения тензора values с одним или несколькими RowPartitions, обеспечивая полное кодирование разряженного тензора (т. е. тензора с переменной длиной измерений).

RowPartition можно определить с помощью нескольких различных схем:

• row_lengths: целочисленный вектор формы [nrows], который определяет длину каждой строки.

• row_splits: целочисленный вектор формы [nrows+1], определяющий «точки разделения» между каждой строкой.

• row_starts: целочисленный вектор формы [nrows], который определяет начальный смещение для каждой строки. Эквивалентно row_splits[:-1].

• row_limits: целочисленный вектор формы [nrows], который определяет конечный смещение для каждой строки. Эквивалентно row_splits[1:].

• value_rowids — это целочисленный вектор формы [nvals], соответствующий попарно значениям последовательности, который указывает строку, к которой принадлежит каждое значение. Если разбиение имеет пустые хвостовые строки, то также должен быть указан nrows.

• uniform_row_length — это целочисленная скалярная величина, определяющая длину каждой строки. Эта схема может быть использована только в том случае, если все строки имеют одинаковую длину.

Например, следующие RowPartitions все представляют разбиение 8 значений на 5 подсписков следующим образом: [[*, *, *, *], [], [*, *, *], [*], []].

p1 = RowPartition.from_row_lengths([4, 0, 3, 1, 0])
p2 = RowPartition.from_row_splits([0, 4, 4, 7, 8, 8])
p3 = RowPartition.from_row_starts([0, 4, 4, 7, 8], nvals=8)
p4 = RowPartition.from_row_limits([4, 4, 7, 8, 8])
p5 = RowPartition.from_value_rowids([0, 0, 0, 0, 2, 2, 2, 3], nrows=5)

Дополнительную информацию о каждой схеме см. в документации к соответствующему методу-фабрикату. Дополнительные примеры см. в документации по tf.RaggedTensor.

Предвычисленные кодирования

RowPartition всегда хранит как минимум одно кодирование разбиения, но его также можно настроить на кэширование дополнительных кодирований. Это позволяет избежать ненужных вычислений в режиме eager. (В режиме графа оптимизации, такие как устранение общих подвыражений, обычно препятствуют этим ненужным вычислениям.) Чтобы проверить, какие кодирования были предвычислены, используйте RowPartition.has_precomputed_<encoding>. Чтобы кэшировать дополнительное кодирование, используйте RowPartition.with_precomputed_<encoding>.

self.row_lengths().shape == [self.static_nrows]
self.row_starts().shape == [self.static_nrows]
self.row_limits().shape == [self.static_nrows]
self.row_splits().shape == [self.static_nrows + 1]

self.value_rowids().shape == [self.static_vals]

Методы

from_row_lengths

Просмотреть исходный код

@classmethod
from_row_lengths(
    row_lengths, validate=True, dtype=None, dtype_hint=None
)

Создает RowPartition, разбивая строки по row_lengths.

Этот RowPartition разбивает последовательность values на строки, указывая длину каждой строки:

partitioned_rows = [[values.pop(0) for _ in range(length)]
                    for length in row_lengths]

from_row_limits

Просмотреть исходный код

@classmethod
from_row_limits(
    row_limits, validate=True, dtype=None, dtype_hint=None
)

Создает RowPartition, разбивая строки по row_limits.

Эквивалентно: from_row_splits(values, concat([0, row_limits], axis=0)).

from_row_splits

Просмотреть исходный код

@classmethod
from_row_splits(
    row_splits, validate=True, dtype=None, dtype_hint=None
)

Создаёт RowPartition, разбивая строки по row_splits.

Этот RowPartition разбивает последовательность values на строки, указывая, где начинается и заканчивается каждая строка:

partitioned_rows = []
for i in range(len(row_splits) - 1):
  row_start = row_splits[i]
  row_end = row_splits[i + 1]
  partitioned_rows.append(values[row_start:row_end])

from_row_starts

Просмотреть исходный код

@classmethod
from_row_starts(
    row_starts, nvals, validate=True, dtype=None, dtype_hint=None
)

Создаёт RowPartition, разбивая строки по row_starts.

Эквивалентно: from_row_splits(concat([row_starts, nvals], axis=0)).

from_uniform_row_length

Просмотреть исходный код

@classmethod
from_uniform_row_length(
    uniform_row_length,
    nvals=None,
    nrows=None,
    validate=True,
    dtype=None,
    dtype_hint=None
)

Создаёт объект RowPartition с разбитыми на строки, используя uniform_row_length.

Это разбиение делит последовательность values на строки, у которых одинаковая длина:

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

Обратите внимание, что необходимо указать либо nvals, либо nrows, либо оба.

from_value_rowids

Просмотреть исходный код

@classmethod
from_value_rowids(
    value_rowids, nrows=None, validate=True, dtype=None, dtype_hint=None
)

Создаёт объект RowPartition с разбитыми на строки, используя value_rowids.

Это разбиение делит последовательность values на строки, указывая, в какую строку должен быть добавлен каждый элемент:

partitioned_rows = [[] for _ in nrows]
for (value, rowid) in zip(values, value_rowids):
  partitioned_rows[rowid].append(value)
``

<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Args</th></tr>

<tr>
<td>
`value_rowids`
</td>
<td>
A 1-D integer tensor with shape `[nvals]`, which corresponds
one-to-one with `values`, and specifies each value's row index.  Must be
nonnegative, and must be sorted in ascending order.
</td>
</tr><tr>
<td>
`nrows`
</td>
<td>
An integer scalar specifying the number of rows.  This should be
specified if the `RowPartition` may containing empty training rows. Must
be greater than `value_rowids[-1]` (or greater than or equal to zero if
`value_rowids` is empty). Defaults to `value_rowids[-1] + 1` (or zero if
`value_rowids` is empty).
</td>
</tr><tr>
<td>
`validate`
</td>
<td>
If true, then use assertions to check that the arguments form a
valid `RowPartition`.
</td>
</tr><tr>
<td>
`dtype`
</td>
<td>
Optional dtype for the RowPartition. If missing, the type
is inferred from the type of `value_rowids`, dtype_hint, or tf.int64.
</td>
</tr><tr>
<td>
`dtype_hint`
</td>
<td>
Optional dtype for the RowPartition, used when dtype
is None. In some cases, a caller may not have a dtype in mind when
converting to a tensor, so dtype_hint can be used as a soft preference.
If the conversion to `dtype_hint` is not possible, this argument has no
effect.
</td>
</tr>
</table>



<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
A `RowPartition`.
</td>
</tr>

</table>



<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Raises</th></tr>

<tr>
<td>
`ValueError`
</td>
<td>
If `nrows` is incompatible with `value_rowids`.
</td>
</tr>
</table>


#### Example:

<pre class="devsite-click-to-copy prettyprint lang-py">
<code class="devsite-terminal" data-terminal-prefix="&gt;&gt;&gt;">print(RowPartition.from_value_rowids(</code>
<code class="devsite-terminal" data-terminal-prefix="...">    value_rowids=[0, 0, 0, 0, 2, 2, 2, 3],</code>
<code class="devsite-terminal" data-terminal-prefix="...">    nrows=4))</code>
<code class="no-select nocode">tf.RowPartition(row_splits=[0 4 4 7 8])</code>
</pre>


<h3 id="is_uniform"><code>is_uniform</code></h3>

<a target="_blank" class="external" href="https://github.com/tensorflow/tensorflow/blob/v2.9.0/tensorflow/python/ops/ragged/row_partition.py#L921-L932">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>is_uniform()
</code></pre>

Returns true if the partition is known to be uniform statically.

This is based upon the existence of self._uniform_row_length. For example:
RowPartition.from_row_lengths([3,3,3]).is_uniform()==false
RowPartition.from_uniform_row_length(5, nvals=20).is_uniform()==true
RowPartition.from_row_lengths([2,0,2]).is_uniform()==false

<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
Whether a RowPartition is known to be uniform statically.
</td>
</tr>

</table>



<h3 id="nrows"><code>nrows</code></h3>

<a target="_blank" class="external" href="https://github.com/tensorflow/tensorflow/blob/v2.9.0/tensorflow/python/ops/ragged/row_partition.py#L777-L789">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>nrows()
</code></pre>

Returns the number of rows created by this `RowPartition`.


<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
scalar integer Tensor
</td>
</tr>

</table>



<h3 id="nvals"><code>nvals</code></h3>

<a target="_blank" class="external" href="https://github.com/tensorflow/tensorflow/blob/v2.9.0/tensorflow/python/ops/ragged/row_partition.py#L762-L775">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>nvals()
</code></pre>

Returns the number of values partitioned by this `RowPartition`.

If the sequence partitioned by this `RowPartition` is a tensor, then
`nvals` is the size of that tensor's outermost dimension -- i.e.,
`nvals == values.shape[0]`.

<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
scalar integer Tensor
</td>
</tr>

</table>



<h3 id="offsets_in_rows"><code>offsets_in_rows</code></h3>

<a target="_blank" class="external" href="https://github.com/tensorflow/tensorflow/blob/v2.9.0/tensorflow/python/ops/ragged/row_partition.py#L903-L919">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>offsets_in_rows()
</code></pre>

Return the offset of each value.

RowPartition takes an array x and converts it into sublists.
offsets[i] is the index of x[i] in its sublist.
Given a shape, such as:
[*,*,*],[*,*],[],[*,*]
This returns:
0,1,2,0,1,0,1

<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
an offset for every value.
</td>
</tr>

</table>



<h3 id="row_lengths"><code>row_lengths</code></h3>

<a target="_blank" class="external" href="https://github.com/tensorflow/tensorflow/blob/v2.9.0/tensorflow/python/ops/ragged/row_partition.py#L829-L840">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>row_lengths()
</code></pre>

Returns the lengths of rows in this `RowPartition`.


<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
A 1-D integer Tensor with shape `[self.nrows]`.
The returned tensor is nonnegative.
`tf.reduce_sum(self.row_lengths) == self.nvals()`.
</td>
</tr>

</table>



<h3 id="row_limits"><code>row_limits</code></h3>

<a target="_blank" class="external" href="https://github.com/tensorflow/tensorflow/blob/v2.9.0/tensorflow/python/ops/ragged/row_partition.py#L816-L827">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>row_limits()
</code></pre>

Returns the limit indices for rows in this row partition.

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

<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
A 1-D integer Tensor with shape `[self.nrows]`.
The returned tensor is nonnegative, and is sorted in ascending order.
`self.row_limits()[-1] == self.nvals()`.
</td>
</tr>

</table>



<h3 id="row_splits"><code>row_splits</code></h3>

<a target="_blank" class="external" href="https://github.com/tensorflow/tensorflow/blob/v2.9.0/tensorflow/python/ops/ragged/row_partition.py#L733-L746">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>row_splits()
</code></pre>

Returns the row-split indices for this row partition.

`row_splits` specifies where the values for each row begin and end.
In particular, the values for row `i` are stored in the slice
`values[row_splits[i]:row_splits[i+1]]`.

<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
A 1-D integer `Tensor` with shape `[self.nrows+1]`.
The returned tensor is non-empty, and is sorted in ascending order.
`self.row_splits()[0] == 0`.
`self.row_splits()[-1] == self.nvals()`.
</td>
</tr>

</table>



<h3 id="row_starts"><code>row_starts</code></h3>

<a target="_blank" class="external" href="https://github.com/tensorflow/tensorflow/blob/v2.9.0/tensorflow/python/ops/ragged/row_partition.py#L802-L814">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>row_starts()
</code></pre>

Returns the start indices for rows in this row partition.

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

<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
A 1-D integer Tensor with shape `[self.nrows()]`.
The returned tensor is nonnegative, and is sorted in ascending order.
`self.row_starts()[0] == 0`.
`self.row_starts()[-1] <= self.nvals()`.
</td>
</tr>

</table>



<h3 id="uniform_row_length"><code>uniform_row_length</code></h3>

<a target="_blank" class="external" href="https://github.com/tensorflow/tensorflow/blob/v2.9.0/tensorflow/python/ops/ragged/row_partition.py#L791-L800">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>uniform_row_length()
</code></pre>

Returns the length of each row in this partition, if rows are uniform.

If all rows in this `RowPartition` have the same length, then this returns
that length as a scalar integer `Tensor`.  Otherwise, it returns `None`.

<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
scalar Tensor with `type=self.dtype`, or `None`.
</td>
</tr>

</table>



<h3 id="value_rowids"><code>value_rowids</code></h3>

<a target="_blank" class="external" href="https://github.com/tensorflow/tensorflow/blob/v2.9.0/tensorflow/python/ops/ragged/row_partition.py#L748-L760">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>value_rowids()
</code></pre>

Returns the row indices for this row partition.

`value_rowids` specifies the row index fo reach value.  In particular,
`value_rowids[i]` is the row index for `values[i]`.

<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
A 1-D integer `Tensor` with shape `[self.nvals()]`.
The returned tensor is nonnegative, and is sorted in ascending order.
</td>
</tr>

</table>



<h3 id="with_dtype"><code>with_dtype</code></h3>

<a target="_blank" class="external" href="https://github.com/tensorflow/tensorflow/blob/v2.9.0/tensorflow/python/ops/ragged/row_partition.py#L963-L986">View source</a>

<pre class="devsite-click-to-copy prettyprint lang-py tfo-signature-link">
<code>with_dtype(
    dtype
)
</code></pre>

Returns a copy of this RowPartition with the given encoding dtype.


<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Args</th></tr>

<tr>
<td>
`dtype`
</td>
<td>
The dtype for encoding tensors, such as `row_splits` and `nrows`.
One of <a href="../../tf#int32"><code>tf.int32</code></a> or <a href="../../tf#int64"><code>tf.int64</code></a>.
</td>
</tr>
</table>



<!-- Tabular view -->
 <table class="responsive fixed orange">
<colgroup><col width="214px"><col></colgroup>
<tr><th colspan="2">Returns</th></tr>
<tr class="alt">
<td colspan="2">
A copy of this RowPartition, with the encoding tensors cast to the given
type.
</td>
</tr>

</table>