tf.io.RaggedFeature  |  TensorFlow v2.16.1 (original) (raw)

Configuration for passing a RaggedTensor input feature.

View aliases

Compat aliases for migration

SeeMigration guide for more details.

tf.compat.v1.io.RaggedFeature

tf.io.RaggedFeature(
    dtype,
    value_key=None,
    partitions=(),
    row_splits_dtype=tf.dtypes.int32,
    validate=False
)

Used in the notebooks

value_key specifies the feature key for a variable-length list of values; and partitions specifies zero or more feature keys for partitioning those values into higher dimensions. Each element of partitions must be one of the following:

• tf.io.RaggedFeature.RowSplits(key: string)
• tf.io.RaggedFeature.RowLengths(key: string)
• tf.io.RaggedFeature.RowStarts(key: string)
• tf.io.RaggedFeature.RowLimits(key: string)
• tf.io.RaggedFeature.ValueRowIds(key: string)
• tf.io.RaggedFeature.UniformRowLength(length: int).

Where key is a feature key whose values are used to partition the values. Partitions are listed from outermost to innermost.

• If len(partitions) == 0 (the default), then:
  • A feature from a single tf.Example is parsed into a 1D tf.Tensor.
  • A feature from a batch of tf.Examples is parsed into a 2Dtf.RaggedTensor, where the outer dimension is the batch dimension, and the inner (ragged) dimension is the feature length in each example.
• If len(partitions) == 1, then:
  • A feature from a single tf.Example is parsed into a 2Dtf.RaggedTensor, where the values taken from the value_key are separated into rows using the partition key.
  • A feature from a batch of tf.Examples is parsed into a 3Dtf.RaggedTensor, where the outer dimension is the batch dimension, the two inner dimensions are formed by separating the value_key values from each example into rows using that example's partition key.
• If len(partitions) > 1, then:
  • A feature from a single tf.Example is parsed into a tf.RaggedTensorwhose rank is len(partitions)+1, and whose ragged_rank islen(partitions).
  • A feature from a batch of tf.Examples is parsed into a tf.RaggedTensorwhose rank is len(partitions)+2 and whose ragged_rank islen(partitions)+1, where the outer dimension is the batch dimension.

There is one exception: if the final (i.e., innermost) element(s) ofpartitions are UniformRowLengths, then the values are simply reshaped (as a higher-dimensional tf.Tensor), rather than being wrapped in atf.RaggedTensor.

Examples

import google.protobuf.text_format as pbtext example_batch = [ pbtext.Merge(r''' features { feature {key: "v" value {int64_list {value: [3, 1, 4, 1, 5, 9]} } } feature {key: "s1" value {int64_list {value: [0, 2, 3, 3, 6]} } } feature {key: "s2" value {int64_list {value: [0, 2, 3, 4]} } } }''', tf.train.Example()).SerializeToString(), pbtext.Merge(r''' features { feature {key: "v" value {int64_list {value: [2, 7, 1, 8, 2, 8, 1]} } } feature {key: "s1" value {int64_list {value: [0, 3, 4, 5, 7]} } } feature {key: "s2" value {int64_list {value: [0, 1, 1, 4]} } } }''', tf.train.Example()).SerializeToString()]

features = { # Zero partitions: returns 1D tf.Tensor for each Example. 'f1': tf.io.RaggedFeature(value_key="v", dtype=tf.int64), # One partition: returns 2D tf.RaggedTensor for each Example. 'f2': tf.io.RaggedFeature(value_key="v", dtype=tf.int64, partitions=[ tf.io.RaggedFeature.RowSplits("s1")]), # Two partitions: returns 3D tf.RaggedTensor for each Example. 'f3': tf.io.RaggedFeature(value_key="v", dtype=tf.int64, partitions=[ tf.io.RaggedFeature.RowSplits("s2"), tf.io.RaggedFeature.RowSplits("s1")]) }

feature_dict = tf.io.parse_single_example(example_batch[0], features) for (name, val) in sorted(feature_dict.items()): print('%s: %s' % (name, val)) f1: tf.Tensor([3 1 4 1 5 9], shape=(6,), dtype=int64) f2: <tf.RaggedTensor [[3, 1], [4], [], [1, 5, 9]]> f3: <tf.RaggedTensor [[[3, 1], [4]], [[]], [[1, 5, 9]]]>

feature_dict = tf.io.parse_example(example_batch, features) for (name, val) in sorted(feature_dict.items()): print('%s: %s' % (name, val)) f1: <tf.RaggedTensor [[3, 1, 4, 1, 5, 9], [2, 7, 1, 8, 2, 8, 1]]> f2: <tf.RaggedTensor [[[3, 1], [4], [], [1, 5, 9]], [[2, 7, 1], [8], [2], [8, 1]]]> f3: <tf.RaggedTensor [[[[3, 1], [4]], [[]], [[1, 5, 9]]], [[[2, 7, 1]], [], [[8], [2], [8, 1]]]]>

Child Classes

class RowLengths

class RowLimits

class RowSplits

class RowStarts

class UniformRowLength

class ValueRowIds