tf.experimental.StructuredTensor

Многомерное множество структур с одинаковой схемой.

Наследует от: BatchableExtensionType, ExtensionType

tf.experimental.StructuredTensor(
    fields: Mapping[str, _FieldValue],
    ragged_shape: tf.experimental.DynamicRaggedShape
)

StructuredTensor — это многомерное множество структур с одинаковой схемой, где:

• Схема — это набор полей, каждое из которых имеет имя и тип.
• Структура сопоставляет каждое поле в схеме с тензорным значением (которое может быть вложенным StructuredTensor).

В качестве важного частного случая, одномерный StructuredTensor кодирует двумерную таблицу, где столбцы являются гетерогенными Tensor, а строки — выровненные элементы в каждом из этих Tensor.

Внутренне StructuredTensors используют кодирование «поля-главное»: для каждого листового поля существует один тензор, который хранит значение этого поля для всех структур в StructuredTensor.

Примеры

# A scalar StructuredTensor describing a single person.
s1 = tf.experimental.StructuredTensor.from_pyval(
    {"age": 82, "nicknames": ["Bob", "Bobby"]})
s1.shape
TensorShape([])
s1["age"]
<tf.Tensor: shape=(), dtype=int32, numpy=82>

# A vector StructuredTensor describing three people.
s2 = tf.experimental.StructuredTensor.from_pyval([
    {"age": 12, "nicknames": ["Josaphine"]},
    {"age": 82, "nicknames": ["Bob", "Bobby"]},
    {"age": 42, "nicknames": ["Elmo"]}])
s2.shape
TensorShape([3])
s2[0]["age"]
<tf.Tensor: shape=(), dtype=int32, numpy=12>

Пути полей

Путь полей — это кортеж имён полей, определяющий путь к вложенному полю.

x = {'a': 1, 'b': ['foo', 'bar', 'baz']}       # shape = [] (scalar)

s1 = [[x, x, x, x], [x, x, x, x]]              # shape = [2, 4]
tf.experimental.StructuredTensor.from_pyval(s1).row_partitions
(tf.RowPartition(row_splits=[0 4 8]),)

s2 = [[x, x], [x, x], [x, x], [x, x]]          # shape = [4, 2]
tf.experimental.StructuredTensor.from_pyval(s2).row_partitions
(tf.RowPartition(row_splits=[0 2 4 6 8]),)

s3 = [[x, x, x], [], [x, x, x, x], [x]]        # shape = [2, None]
tf.experimental.StructuredTensor.from_pyval(s3).row_partitions
(tf.RowPartition(row_splits=[0 3 3 7 8]),)

s4 = [[[x, x], [x, x]], [[x, x], [x, x]]]      # shape = [2, 2, 2]
tf.experimental.StructuredTensor.from_pyval(s4).row_partitions
(tf.RowPartition(row_splits=[0 2 4]),
 tf.RowPartition(row_splits=[0 2 4 6 8]))

s5 = [[[x, x], [x]], [[x, x]], [[x, x], [x]]]  # shape = [3, None, None]
tf.experimental.StructuredTensor.from_pyval(s5).row_partitions
(tf.RowPartition(row_splits=[0 2 3 5]),
 tf.RowPartition(row_splits=[0 2 3 5 7 8]))

Подклассы

class Spec

Методы

field_names

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

field_names()

Возвращает строковые имена полей для этого StructuredTensor.

field_value

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

field_value(
    field_name
)

Возвращает тензорное значение для указанного поля или пути.

Если field_name является string, то оно напрямую указывает на поле, принадлежащее этому StructuredTensor. Если у этого StructuredTensor форма [D1...DN], то возвращаемый тензор будет иметь форму [D1...DN, V1...VM], где срез result[d1...dN] содержит значение поля для структуры в позиции self[d1...dN].

Если field_name является tuple из string, то оно определяет путь к полю, принадлежащему вложенному StructuredTensor. В частности, struct.field_value((f1, f2, ..., fN)) эквивалентно struct.field_value(f1).field_value(f2)....field_value(fN)

from_fields

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

@classmethod
from_fields(
    fields, shape=(), nrows=None, row_partitions=None, validate=False
)

Создаёт StructuredTensor из словаря полей.

>>> tf.experimental.StructuredTensor.from_fields({'x': 1, 'y': [1, 2, 3]})
<StructuredTensor(
  fields={
    "x": tf.Tensor(1, shape=(), dtype=int32),
    "y": tf.Tensor([1 2 3], shape=(3,), dtype=int32)},
  shape=())>

tf.experimental.StructuredTensor.from_fields(
    {'foo': [1, 2], 'bar': [3, 4]}, shape=[2])
<StructuredTensor(
  fields={
    "bar": tf.Tensor([3 4], shape=(2,), dtype=int32),
    "foo": tf.Tensor([1 2], shape=(2,), dtype=int32)},
  shape=(2,))>

from_fields_and_rank

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

@classmethod
from_fields_and_rank(
    fields: Mapping[str, _FieldValue],
    rank: int,
    validate: bool = False,
    dtype: Optional[tf.dtypes.DType] = None
) -> 'StructuredTensor'

Создаёт StructuredTensor из непустого словаря полей.

Обратите внимание, что если тип формы не задан, он будет определен по любому полю, имеющему тип формы. Если поля отличаются, то int64 будет предпочтительнее int32, потому что преобразование из int32 в int64 безопаснее, чем из int64 в int32.

Если нет полей с разряженной формой, то по умолчанию это будет int64, но в будущем это будет изменено на int32.

>>> tf.experimental.StructuredTensor.from_fields_and_rank(
...     {'x': 1, 'y': [1, 2, 3]}, 0)
<StructuredTensor(
  fields={
    "x": tf.Tensor(1, shape=(), dtype=int32),
    "y": tf.Tensor([1 2 3], shape=(3,), dtype=int32)},
  shape=())>
>>> StructuredTensor.from_fields_and_rank({'foo': [1, 2], 'bar': [3, 4]},
...                              1)
<StructuredTensor(
  fields={
    "bar": tf.Tensor([3 4], shape=(2,), dtype=int32),
    "foo": tf.Tensor([1 2], shape=(2,), dtype=int32)},
  shape=(2,))>

from_pyval

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

@classmethod
from_pyval(
    pyval, typespec=None
)

Создает StructuredTensor из вложенной структуры Python.

tf.experimental.StructuredTensor.from_pyval(
    {'a': [1, 2, 3], 'b': [[4, 5], [6, 7]]})
<StructuredTensor(
    fields={
      "a": tf.Tensor([1 2 3], shape=(3,), dtype=int32),
      "b": <tf.RaggedTensor [[4, 5], [6, 7]]>},
    shape=())>

Обратите внимание, что StructuredTensor.from_pyval(pyval).to_pyval() == pyval.

from_shape

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

@classmethod
from_shape(
    ragged_shape: tf.experimental.DynamicRaggedShape
) -> 'StructuredTensor'

Создает StructuredTensor без полей и ragged_shape.

merge_dims

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

merge_dims(
    outer_axis, inner_axis
)

Объединяет outer_axis...inner_axis в одно измерение.

Возвращает копию этого RaggedTensor с указанным диапазоном измерений, сжатым в одно измерение, с элементами в порядке следования строк.

st = tf.experimental.StructuredTensor.from_pyval(
    [[{'foo': 12}, {'foo': 33}], [], [{'foo': 99}]])
st.merge_dims(0, 1)
<StructuredTensor(
  fields={
    "foo": tf.Tensor([12 33 99], shape=(3,), dtype=int32)},
  shape=(3,))>

nrows

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

nrows()

Количество строк в этом StructuredTensor (если ранг > 0).

Это означает длину внешнего измерения StructuredTensor.

Обратите внимание, что если self.rank > 1, то это равно количеству строк первой части строки. То есть self.nrows() == self.row_partitions[0].nrows().

В противном случае self.nrows() будет первым измерением значений поля.

partition_outer_dimension

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

partition_outer_dimension(
    row_partition
)

Разделяет внешнее измерение этого StructuredTensor.

Возвращает новый StructuredTensor с теми же значениями, что и self, где внешнее измерение разделено на два (возможно, разрозненных) измерения. Требуется, чтобы у этого StructuredTensor было внешнее измерение (т. е. self.shape.rank > 0).

st = tf.experimental.StructuredTensor.from_pyval(
    [{'foo': 12}, {'foo': 33}, {'foo': 99}])
partition = RowPartition.from_row_lengths([2, 0, 1])
st.partition_outer_dimension(partition)
<StructuredTensor(
  fields={
    "foo": <tf.RaggedTensor [[12, 33], [], [99]]>},
  shape=(3, None))>

promote

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

promote(
    source_path, new_name
)

Повышает поле, объединяя измерения между прародителем и родителем.

d = [
 {'docs': [{'tokens':[1, 2]}, {'tokens':[3]}]},
 {'docs': [{'tokens':[7]}]}]
st = tf.experimental.StructuredTensor.from_pyval(d)
st2 =st.promote(('docs','tokens'), 'docs_tokens')
st2[0]['docs_tokens']
<tf.Tensor: shape=(3,), dtype=int32, numpy=array([1, 2, 3], dtype=int32)>
st2[1]['docs_tokens']
<tf.Tensor: shape=(1,), dtype=int32, numpy=array([7], dtype=int32)>

to_pyval

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

to_pyval()

Возвращает этот StructuredTensor как вложенный словарь Python или список словарей.

Преобразует этот StructuredTensor в вложенное значение Python:

• StructTensors с rank=0 преобразуются в словарь с записью для каждого поля. Имена полей используются в качестве ключей, а значения полей преобразуются в значения Python. В частности:

  • Поля тензора скаляра преобразуются в простые значения (такие как int или float или string)
  • Поля тензоров, не являющихся скалярами, и поля RaggedTensor преобразуются во вложенные списки простых значений.
  • Поля StructuredTensor преобразуются рекурсивно с использованием to_pyval.

• StructTensors с rank>0 преобразуются во вложенные списки Python list, содержащие по одному словарю для каждой структуры (где словарь каждой структуры определяется, как описано выше).

Требуется, чтобы все поля были тензорами Eager.

tf.experimental.StructuredTensor.from_fields(
    {'a': [1, 2, 3]}, [3]).to_pyval()
[{'a': 1}, {'a': 2}, {'a': 3}]

Обратите внимание, что StructuredTensor.from_pyval(pyval).to_pyval() == pyval.

with_shape_dtype

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

with_shape_dtype(
    dtype: tf.dtypes.DType
) -> 'StructuredTensor'

with_updates

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

with_updates(
    updates: Dict[FieldName, Union[_FieldValue, _FieldFn, None]],
    validate: bool = False
) -> 'StructuredTensor'

Создает новый StructuredTensor с обновленными полями.

Если этот StructuredTensor является скаляром, и k — обновляемое FieldName, а v — новое значение, то:

result[k] = v              # If (k, v) is in updates and v is a FieldValue
result[k] = f(self[k])     # If (k, f) is in updates and f is a FieldFn
result[k] = self[k]        # If k is in self.field_names but not in updates

Если этот StructuredTensor имеет ранг N и форму [D1...DN], то каждое FieldValue v в updates должно иметь форму [D1...DN, ...], т. е. с префиксом той же формы, что и StructuredTensor. Тогда результирующий StructuredTensor будет иметь:

result[i1...iN][k] = v[i1...iN]                        # (k, v) in updates
result[i1...iN][k] = f(self.field_value(k))[i1...iN]   # (k, f) in updates
result[i1...iN][k] = self[i1...iN][k]                  # k not in updates

Обратите внимание, что result.shape всегда равно self.shape (но формы вложенных StructuredTensors могут быть изменены, если они обновляются новыми значениями).

Примеры:

shoes_us = tf.experimental.StructuredTensor.from_pyval([
   {"age": 12, "nicknames": ["Josaphine"],
      "shoes": {"sizes": [8.0, 7.5, 7.5]} },
   {"age": 82, "nicknames": ["Bob", "Bobby"],
       "shoes": {"sizes": [11.0, 11.5, 12.0]} },
   {"age": 42, "nicknames": ["Elmo"],
       "shoes": {"sizes": [9.0, 9.5, 10.0]} }])
def us_to_europe(t):
  return tf.round(t * 2.54 + 17.0)  # Rough approximation.
shoe_sizes_key = ("shoes", "sizes")
shoes_eu = shoes_us.with_updates({shoe_sizes_key: us_to_europe})
shoes_eu.field_value(shoe_sizes_key)
<tf.RaggedTensor [[37.0, 36.0, 36.0], [45.0, 46.0, 47.0],
[40.0, 41.0, 42.0]]>

__eq__

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

__eq__(
    other
)

Возвращает self==value.

__getitem__

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

__getitem__(
    key
)

Возвращает указанную часть этого StructuredTensor.

• Если struct_tensor скалярно (т. е. одна структура), то struct_tensor[f] возвращает значение поля f (где f должна быть строкой).

• Если struct_tensor нескалярно (т. е. вектор или многомерный тензор структур), struct_tensor[i] выбирает элемент или срез тензора с помощью стандартной семантики Python (например, отрицательные значения индексируются с конца). i может иметь один из следующих типов:

  • int константа
  • string константа
  • скалярное целое число Tensor
  • slice содержащая целочисленные константы и/или скалярные целые числа Tensor

Многомерная индексация

StructuredTensor поддерживает многомерную индексацию. Т. е. key может быть tuple значений, индексирующих или срезающих несколько измерений одновременно. Например, если people — это вектор структур, каждая из которых имеет векторно-значное поле names, то people[3, 'names', 0] эквивалентно people[3]['names'][0]; и people[:, 'names', :] вернёт (возможно, разреженный) массив имён с формой [num_people, num_names_per_person].

__ne__

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

__ne__(
    other
)

Возвращает self!=value.