Functions that work with structures.
A structure is either:
- one of the recognized Python collections, holding nested structures;
- a value of any other type, typically a TensorFlow data type like Tensor, Variable, or of compatible types such as int, float, ndarray, etc. these are commonly referred to as atoms of the structure.
A structure of type T
is a structure whose atomic items are of type T
.
For example, a structure of tf.Tensor
only contains tf.Tensor
as its atoms.
Historically a nested structure was called a nested sequence in TensorFlow. A nested structure is sometimes called a nest or a tree, but the formal name nested structure is preferred.
Refer to Nesting Data Structures.
The following collection types are recognized by tf.nest
as nested
structures:
collections.abc.Sequence
(exceptstring
andbytes
). This includeslist
,tuple
, andnamedtuple
.collections.abc.Mapping
(with sortable keys). This includesdict
andcollections.OrderedDict
.collections.abc.MappingView
(with sortable keys).attr.s
classes.
Any other values are considered atoms. Not all collection types are considered nested structures. For example, the following types are considered atoms:
set
;{"a", "b"}
is an atom, while["a", "b"]
is a nested structure.dataclass
classestf.Tensor
numpy.array
tf.nest.is_nested
checks whether an object is a nested structure or an atom.
For example:
tf.nest.is_nested("1234")
False
tf.nest.is_nested([1, 3, [4, 5]])
True
tf.nest.is_nested(((7, 8), (5, 6)))
True
tf.nest.is_nested([])
True
tf.nest.is_nested({"a": 1, "b": 2})
True
tf.nest.is_nested({"a": 1, "b": 2}.keys())
True
tf.nest.is_nested({"a": 1, "b": 2}.values())
True
tf.nest.is_nested({"a": 1, "b": 2}.items())
True
tf.nest.is_nested(set([1, 2]))
False
ones = tf.ones([2, 3])
tf.nest.is_nested(ones)
False
Functions
assert_same_structure(...)
: Asserts that two structures are nested in the same way.
flatten(...)
: Returns a flat list from a given structure.
is_nested(...)
: Returns true if its input is a nested structure.
map_structure(...)
: Creates a new structure by applying func
to each atom in structure
.
pack_sequence_as(...)
: Returns a given flattened sequence packed into a given structure.