tf.RaggedTensor       View source on GitHub    Represents a ragged tensor.  View aliases  Compat aliases for migration
See Migration guide for more details. tf.compat.v1.RaggedTensor  A RaggedTensor is a tensor with one or more ragged dimensions, which are dimensions whose slices may have different lengths. For example, the inner (column) dimension of rt=[[3, 1, 4, 1], [], [5, 9, 2], [6], []] is ragged, since the column slices (rt[0, :], ..., rt[4, :]) have different lengths. Dimensions whose slices all have the same length are called uniform dimensions. The outermost dimension of a RaggedTensor is always uniform, since it consists of a single slice (and so there is no possibility for differing slice lengths). The total number of dimensions in a RaggedTensor is called its rank, and the number of ragged dimensions in a RaggedTensor is called its ragged-rank. A RaggedTensor's ragged-rank is fixed at graph creation time: it can't depend on the runtime values of Tensors, and can't vary dynamically for different session runs. Note that the __init__ constructor is private. Please use one of the following methods to construct a RaggedTensor: * tf.RaggedTensor.from_row_lengths
* tf.RaggedTensor.from_value_rowids
* tf.RaggedTensor.from_row_splits
* tf.RaggedTensor.from_row_starts
* tf.RaggedTensor.from_row_limits
* tf.RaggedTensor.from_nested_row_splits
* tf.RaggedTensor.from_nested_row_lengths
* tf.RaggedTensor.from_nested_value_rowids
 Potentially Ragged Tensors Many ops support both Tensors and RaggedTensors. The term "potentially ragged tensor" may be used to refer to a tensor that might be either a Tensor or a RaggedTensor. The ragged-rank of a Tensor is zero. Documenting RaggedTensor Shapes When documenting the shape of a RaggedTensor, ragged dimensions can be indicated by enclosing them in parentheses. For example, the shape of a 3-D RaggedTensor that stores the fixed-size word embedding for each word in a sentence, for each sentence in a batch, could be written as [num_sentences, (num_words), embedding_size]. The parentheses around (num_words) indicate that dimension is ragged, and that the length of each element list in that dimension may vary for each item. Component Tensors Internally, a RaggedTensor consists of a concatenated list of values that are partitioned into variable-length rows. In particular, each RaggedTensor consists of:  A values tensor, which concatenates the variable-length rows into a flattened list. For example, the values tensor for [[3, 1, 4, 1], [], [5, 9, 2], [6], []] is [3, 1, 4, 1, 5, 9, 2, 6]. A row_splits vector, which indicates how those flattened values are divided into rows. In particular, the values for row rt[i] are stored in the slice rt.values[rt.row_splits[i]:rt.row_splits[i+1]].  Example:
print(tf.RaggedTensor.from_row_splits(
      values=[3, 1, 4, 1, 5, 9, 2, 6],
      row_splits=[0, 4, 4, 7, 8, 8]))
<tf.RaggedTensor [[3, 1, 4, 1], [], [5, 9, 2], [6], []]>
 Alternative Row-Partitioning Schemes In addition to row_splits, ragged tensors provide support for five other row-partitioning schemes:  row_lengths: a vector with shape [nrows], which specifies the length of each row. value_rowids and nrows: value_rowids is a vector with shape [nvals], corresponding one-to-one with values, which specifies each value's row index. In particular, the row rt[row] consists of the values rt.values[j] where value_rowids[j]==row. nrows is an integer scalar that specifies the number of rows in the RaggedTensor. (nrows is used to indicate trailing empty rows.) row_starts: a vector with shape [nrows], which specifies the start offset of each row. Equivalent to row_splits[:-1]. row_limits: a vector with shape [nrows], which specifies the stop offset of each row. Equivalent to row_splits[1:]. uniform_row_length: A scalar tensor, specifying the length of every row. This row-partitioning scheme may only be used if all rows have the same length.  Example: The following ragged tensors are equivalent, and all represent the nested list [[3, 1, 4, 1], [], [5, 9, 2], [6], []].
values = [3, 1, 4, 1, 5, 9, 2, 6]
rt1 = RaggedTensor.from_row_splits(values, row_splits=[0, 4, 4, 7, 8, 8])
rt2 = RaggedTensor.from_row_lengths(values, row_lengths=[4, 0, 3, 1, 0])
rt3 = RaggedTensor.from_value_rowids(
    values, value_rowids=[0, 0, 0, 0, 2, 2, 2, 3], nrows=5)
rt4 = RaggedTensor.from_row_starts(values, row_starts=[0, 4, 4, 7, 8])
rt5 = RaggedTensor.from_row_limits(values, row_limits=[4, 4, 7, 8, 8])
 Multiple Ragged Dimensions RaggedTensors with multiple ragged dimensions can be defined by using a nested RaggedTensor for the values tensor. Each nested RaggedTensor adds a single ragged dimension.
inner_rt = RaggedTensor.from_row_splits(  # =rt1 from above
    values=[3, 1, 4, 1, 5, 9, 2, 6], row_splits=[0, 4, 4, 7, 8, 8])
outer_rt = RaggedTensor.from_row_splits(
    values=inner_rt, row_splits=[0, 3, 3, 5])
print(outer_rt.to_list())
[[[3, 1, 4, 1], [], [5, 9, 2]], [], [[6], []]]
print(outer_rt.ragged_rank)
2
 The factory function RaggedTensor.from_nested_row_splits may be used to construct a RaggedTensor with multiple ragged dimensions directly, by providing a list of row_splits tensors:
RaggedTensor.from_nested_row_splits(
    flat_values=[3, 1, 4, 1, 5, 9, 2, 6],
    nested_row_splits=([0, 3, 3, 5], [0, 4, 4, 7, 8, 8])).to_list()
[[[3, 1, 4, 1], [], [5, 9, 2]], [], [[6], []]]
 Uniform Inner Dimensions RaggedTensors with uniform inner dimensions can be defined by using a multidimensional Tensor for values.
rt = RaggedTensor.from_row_splits(values=tf.ones([5, 3], tf.int32),
                                  row_splits=[0, 2, 5])
print(rt.to_list())
[[[1, 1, 1], [1, 1, 1]],
 [[1, 1, 1], [1, 1, 1], [1, 1, 1]]]
print(rt.shape)
(2, None, 3)
 Uniform Outer Dimensions RaggedTensors with uniform outer dimensions can be defined by using one or more RaggedTensor with a uniform_row_length row-partitioning tensor. For example, a RaggedTensor with shape [2, 2, None] can be constructed with this method from a RaggedTensor values with shape [4, None]:
values = tf.ragged.constant([[1, 2, 3], [4], [5, 6], [7, 8, 9, 10]])
print(values.shape)
(4, None)
rt6 = tf.RaggedTensor.from_uniform_row_length(values, 2)
print(rt6)
<tf.RaggedTensor [[[1, 2, 3], [4]], [[5, 6], [7, 8, 9, 10]]]>
print(rt6.shape)
(2, 2, None)
 Note that rt6 only contains one ragged dimension (the innermost dimension). In contrast, if from_row_splits is used to construct a similar RaggedTensor, then that RaggedTensor will have two ragged dimensions:
rt7 = tf.RaggedTensor.from_row_splits(values, [0, 2, 4])
print(rt7.shape)
(2, None, None)
 Uniform and ragged outer dimensions may be interleaved, meaning that a tensor with any combination of ragged and uniform dimensions may be created. For example, a RaggedTensor t4 with shape [3, None, 4, 8, None, 2] could be constructed as follows: t0 = tf.zeros([1000, 2])                           # Shape:         [1000, 2]
t1 = RaggedTensor.from_row_lengths(t0, [...])      #           [160, None, 2]
t2 = RaggedTensor.from_uniform_row_length(t1, 8)   #         [20, 8, None, 2]
t3 = RaggedTensor.from_uniform_row_length(t2, 4)   #       [5, 4, 8, None, 2]
t4 = RaggedTensor.from_row_lengths(t3, [...])      # [3, None, 4, 8, None, 2]

 Attributes
  dtype   The DType of values in this tensor.
  flat_values   The innermost values tensor for this ragged tensor. Concretely, if rt.values is a Tensor, then rt.flat_values is rt.values; otherwise, rt.flat_values is rt.values.flat_values. Conceptually, flat_values is the tensor formed by flattening the outermost dimension and all of the ragged dimensions into a single dimension. rt.flat_values.shape = [nvals] + rt.shape[rt.ragged_rank + 1:] (where nvals is the number of items in the flattened dimensions). Example:
rt = tf.ragged.constant([[[3, 1, 4, 1], [], [5, 9, 2]], [], [[6], []]])
print(rt.flat_values)
tf.Tensor([3 1 4 1 5 9 2 6], shape=(8,), dtype=int32)

  nested_row_splits   A tuple containing the row_splits for all ragged dimensions. rt.nested_row_splits is a tuple containing the row_splits tensors for all ragged dimensions in rt, ordered from outermost to innermost. In particular, rt.nested_row_splits = (rt.row_splits,) + value_splits where:
value_splits = () if rt.values is a Tensor.
value_splits = rt.values.nested_row_splits otherwise.  Example:
rt = tf.ragged.constant(
    [[[[3, 1, 4, 1], [], [5, 9, 2]], [], [[6], []]]])
for i, splits in enumerate(rt.nested_row_splits):
  print('Splits for dimension %d: %s' % (i+1, splits.numpy()))
Splits for dimension 1: [0 3]
Splits for dimension 2: [0 3 3 5]
Splits for dimension 3: [0 4 4 7 8 8]

  ragged_rank   The number of times the RaggedTensor's flat_values is partitioned.
values = tf.ragged.constant([[1, 2, 3], [4], [5, 6], [7, 8, 9, 10]])
values.ragged_rank
1

rt = tf.RaggedTensor.from_uniform_row_length(values, 2)
rt.ragged_rank
2

  row_splits   The row-split indices for this ragged tensor's values. rt.row_splits specifies where the values for each row begin and end in rt.values. In particular, the values for row rt[i] are stored in the slice rt.values[rt.row_splits[i]:rt.row_splits[i+1]]. Example:
rt = tf.ragged.constant([[3, 1, 4, 1], [], [5, 9, 2], [6], []])
print(rt.row_splits)  # indices of row splits in rt.values
tf.Tensor([0 4 4 7 8 8], shape=(6,), dtype=int64)

  shape   The statically known shape of this ragged tensor.
tf.ragged.constant([[0], [1, 2]]).shape
TensorShape([2, None])

tf.ragged.constant([[[0, 1]], [[1, 2], [3, 4]]], ragged_rank=1).shape
TensorShape([2, None, 2])

  uniform_row_length   The length of each row in this ragged tensor, or None if rows are ragged.
rt1 = tf.ragged.constant([[1, 2, 3], [4], [5, 6], [7, 8, 9, 10]])
print(rt1.uniform_row_length)  # rows are ragged.
None

rt2 = tf.RaggedTensor.from_uniform_row_length(
    values=rt1, uniform_row_length=2)
print(rt2)
<tf.RaggedTensor [[[1, 2, 3], [4]], [[5, 6], [7, 8, 9, 10]]]>
print(rt2.uniform_row_length)  # rows are not ragged (all have size 2).
tf.Tensor(2, shape=(), dtype=int64)
 A RaggedTensor's rows are only considered to be uniform (i.e. non-ragged) if it can be determined statically (at graph construction time) that the rows all have the same length.

  values   The concatenated rows for this ragged tensor. rt.values is a potentially ragged tensor formed by flattening the two outermost dimensions of rt into a single dimension. rt.values.shape = [nvals] + rt.shape[2:] (where nvals is the number of items in the outer two dimensions of rt). rt.ragged_rank = self.ragged_rank - 1 Example:
rt = tf.ragged.constant([[3, 1, 4, 1], [], [5, 9, 2], [6], []])
print(rt.values)
tf.Tensor([3 1 4 1 5 9 2 6], shape=(8,), dtype=int32)

   Methods bounding_shape View source
bounding_shape(
    axis=None, name=None, out_type=None
)
 Returns the tight bounding box shape for this RaggedTensor.

 Args
  axis   An integer scalar or vector indicating which axes to return the bounding box for. If not specified, then the full bounding box is returned.
  name   A name prefix for the returned tensor (optional).
  out_type   dtype for the returned tensor. Defaults to self.row_splits.dtype.

 Returns   An integer Tensor (dtype=self.row_splits.dtype). If axis is not specified, then output is a vector with output.shape=[self.shape.ndims]. If axis is a scalar, then the output is a scalar. If axis is a vector, then output is a vector, where output[i] is the bounding size for dimension axis[i].
 Example:
rt = tf.ragged.constant([[1, 2, 3, 4], [5], [], [6, 7, 8, 9], [10]])
rt.bounding_shape().numpy()
array([5, 4])
 consumers View source
consumers()
 from_nested_row_lengths View source
@classmethod
from_nested_row_lengths(
    flat_values, nested_row_lengths, name=None, validate=True
)
 Creates a RaggedTensor from a nested list of row_lengths tensors. Equivalent to: result = flat_values
for row_lengths in reversed(nested_row_lengths):
  result = from_row_lengths(result, row_lengths)

 Args
  flat_values   A potentially ragged tensor.
  nested_row_lengths   A list of 1-D integer tensors. The ith tensor is used as the row_lengths for the ith ragged dimension.
  name   A name prefix for the RaggedTensor (optional).
  validate   If true, then use assertions to check that the arguments form a valid RaggedTensor. Note: these assertions incur a runtime cost, since they must be checked for each tensor value.

 Returns   A RaggedTensor (or flat_values if nested_row_lengths is empty).
 from_nested_row_splits View source
@classmethod
from_nested_row_splits(
    flat_values, nested_row_splits, name=None, validate=True
)
 Creates a RaggedTensor from a nested list of row_splits tensors. Equivalent to: result = flat_values
for row_splits in reversed(nested_row_splits):
  result = from_row_splits(result, row_splits)

 Args
  flat_values   A potentially ragged tensor.
  nested_row_splits   A list of 1-D integer tensors. The ith tensor is used as the row_splits for the ith ragged dimension.
  name   A name prefix for the RaggedTensor (optional).
  validate   If true, then use assertions to check that the arguments form a valid RaggedTensor. Note: these assertions incur a runtime cost, since they must be checked for each tensor value.

 Returns   A RaggedTensor (or flat_values if nested_row_splits is empty).
 from_nested_value_rowids View source
@classmethod
from_nested_value_rowids(
    flat_values, nested_value_rowids, nested_nrows=None, name=None, validate=True
)
 Creates a RaggedTensor from a nested list of value_rowids tensors. Equivalent to: result = flat_values
for (rowids, nrows) in reversed(zip(nested_value_rowids, nested_nrows)):
  result = from_value_rowids(result, rowids, nrows)

 Args
  flat_values   A potentially ragged tensor.
  nested_value_rowids   A list of 1-D integer tensors. The ith tensor is used as the value_rowids for the ith ragged dimension.
  nested_nrows   A list of integer scalars. The ith scalar is used as the nrows for the ith ragged dimension.
  name   A name prefix for the RaggedTensor (optional).
  validate   If true, then use assertions to check that the arguments form a valid RaggedTensor. Note: these assertions incur a runtime cost, since they must be checked for each tensor value.

 Returns   A RaggedTensor (or flat_values if nested_value_rowids is empty).

 Raises
  ValueError   If len(nested_values_rowids) != len(nested_nrows).    from_row_lengths View source
@classmethod
from_row_lengths(
    values, row_lengths, name=None, validate=True
)
 Creates a RaggedTensor with rows partitioned by row_lengths. The returned RaggedTensor corresponds with the python list defined by: result = [[values.pop(0) for i in range(length)]
          for length in row_lengths]

 Args
  values   A potentially ragged tensor with shape [nvals, ...].
  row_lengths   A 1-D integer tensor with shape [nrows]. Must be nonnegative. sum(row_lengths) must be nvals.
  name   A name prefix for the RaggedTensor (optional).
  validate   If true, then use assertions to check that the arguments form a valid RaggedTensor. Note: these assertions incur a runtime cost, since they must be checked for each tensor value.

 Returns   A RaggedTensor. result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.
 Example:
print(tf.RaggedTensor.from_row_lengths(
    values=[3, 1, 4, 1, 5, 9, 2, 6],
    row_lengths=[4, 0, 3, 1, 0]))
<tf.RaggedTensor [[3, 1, 4, 1], [], [5, 9, 2], [6], []]>
 from_row_limits View source
@classmethod
from_row_limits(
    values, row_limits, name=None, validate=True
)
 Creates a RaggedTensor with rows partitioned by row_limits. Equivalent to: from_row_splits(values, concat([0, row_limits])).

 Args
  values   A potentially ragged tensor with shape [nvals, ...].
  row_limits   A 1-D integer tensor with shape [nrows]. Must be sorted in ascending order. If nrows>0, then row_limits[-1] must be nvals.
  name   A name prefix for the RaggedTensor (optional).
  validate   If true, then use assertions to check that the arguments form a valid RaggedTensor. Note: these assertions incur a runtime cost, since they must be checked for each tensor value.

 Returns   A RaggedTensor. result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.
 Example:
print(tf.RaggedTensor.from_row_limits(
    values=[3, 1, 4, 1, 5, 9, 2, 6],
    row_limits=[4, 4, 7, 8, 8]))
<tf.RaggedTensor [[3, 1, 4, 1], [], [5, 9, 2], [6], []]>
 from_row_splits View source
@classmethod
from_row_splits(
    values, row_splits, name=None, validate=True
)
 Creates a RaggedTensor with rows partitioned by row_splits. The returned RaggedTensor corresponds with the python list defined by: result = [values[row_splits[i]:row_splits[i + 1]]
          for i in range(len(row_splits) - 1)]

 Args
  values   A potentially ragged tensor with shape [nvals, ...].
  row_splits   A 1-D integer tensor with shape [nrows+1]. Must not be empty, and must be sorted in ascending order. row_splits[0] must be zero and row_splits[-1] must be nvals.
  name   A name prefix for the RaggedTensor (optional).
  validate   If true, then use assertions to check that the arguments form a valid RaggedTensor. Note: these assertions incur a runtime cost, since they must be checked for each tensor value.

 Returns   A RaggedTensor. result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.

 Raises
  ValueError   If row_splits is an empty list.    Example:
print(tf.RaggedTensor.from_row_splits(
    values=[3, 1, 4, 1, 5, 9, 2, 6],
    row_splits=[0, 4, 4, 7, 8, 8]))
<tf.RaggedTensor [[3, 1, 4, 1], [], [5, 9, 2], [6], []]>
 from_row_starts View source
@classmethod
from_row_starts(
    values, row_starts, name=None, validate=True
)
 Creates a RaggedTensor with rows partitioned by row_starts. Equivalent to: from_row_splits(values, concat([row_starts, nvals])).

 Args
  values   A potentially ragged tensor with shape [nvals, ...].
  row_starts   A 1-D integer tensor with shape [nrows]. Must be nonnegative and sorted in ascending order. If nrows>0, then row_starts[0] must be zero.
  name   A name prefix for the RaggedTensor (optional).
  validate   If true, then use assertions to check that the arguments form a valid RaggedTensor. Note: these assertions incur a runtime cost, since they must be checked for each tensor value.

 Returns   A RaggedTensor. result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.
 Example:
print(tf.RaggedTensor.from_row_starts(
    values=[3, 1, 4, 1, 5, 9, 2, 6],
    row_starts=[0, 4, 4, 7, 8]))
<tf.RaggedTensor [[3, 1, 4, 1], [], [5, 9, 2], [6], []]>
 from_sparse View source
@classmethod
from_sparse(
    st_input, name=None, row_splits_dtype=tf.dtypes.int64
)
 Converts a 2D tf.sparse.SparseTensor to a RaggedTensor. Each row of the output RaggedTensor will contain the explicit values from the same row in st_input. st_input must be ragged-right. If not it is not ragged-right, then an error will be generated. Example:
indices = [[0, 0], [0, 1], [0, 2], [1, 0], [3, 0]]
st = tf.sparse.SparseTensor(indices=indices,
                            values=[1, 2, 3, 4, 5],
                            dense_shape=[4, 3])
tf.RaggedTensor.from_sparse(st).to_list()
[[1, 2, 3], [4], [], [5]]
 Currently, only two-dimensional SparseTensors are supported.

 Args
  st_input   The sparse tensor to convert. Must have rank 2.
  name   A name prefix for the returned tensors (optional).
  row_splits_dtype   dtype for the returned RaggedTensor's row_splits tensor. One of tf.int32 or tf.int64.

 Returns   A RaggedTensor with the same values as st_input. output.ragged_rank = rank(st_input) - 1. output.shape = [st_input.dense_shape[0], None].

 Raises
  ValueError   If the number of dimensions in st_input is not known statically, or is not two.    from_tensor View source
@classmethod
from_tensor(
    tensor, lengths=None, padding=None, ragged_rank=1, name=None,
    row_splits_dtype=tf.dtypes.int64
)
 Converts a tf.Tensor into a RaggedTensor. The set of absent/default values may be specified using a vector of lengths or a padding value (but not both). If lengths is specified, then the output tensor will satisfy output[row] = tensor[row][:lengths[row]]. If 'lengths' is a list of lists or tuple of lists, those lists will be used as nested row lengths. If padding is specified, then any row suffix consisting entirely of padding will be excluded from the returned RaggedTensor. If neither lengths nor padding is specified, then the returned RaggedTensor will have no absent/default values. Examples:
dt = tf.constant([[5, 7, 0], [0, 3, 0], [6, 0, 0]])
tf.RaggedTensor.from_tensor(dt)
<tf.RaggedTensor [[5, 7, 0], [0, 3, 0], [6, 0, 0]]>
tf.RaggedTensor.from_tensor(dt, lengths=[1, 0, 3])
<tf.RaggedTensor [[5], [], [6, 0, 0]]>

tf.RaggedTensor.from_tensor(dt, padding=0)
<tf.RaggedTensor [[5, 7], [0, 3], [6]]>

dt = tf.constant([[[5, 0], [7, 0], [0, 0]],
                  [[0, 0], [3, 0], [0, 0]],
                  [[6, 0], [0, 0], [0, 0]]])
tf.RaggedTensor.from_tensor(dt, lengths=([2, 0, 3], [1, 1, 2, 0, 1]))
<tf.RaggedTensor [[[5], [7]], [], [[6, 0], [], [0]]]>

 Args
  tensor   The Tensor to convert. Must have rank ragged_rank + 1 or higher.
  lengths   An optional set of row lengths, specified using a 1-D integer Tensor whose length is equal to tensor.shape[0] (the number of rows in tensor). If specified, then output[row] will contain tensor[row][:lengths[row]]. Negative lengths are treated as zero. You may optionally pass a list or tuple of lengths to this argument, which will be used as nested row lengths to construct a ragged tensor with multiple ragged dimensions.
  padding   An optional padding value. If specified, then any row suffix consisting entirely of padding will be excluded from the returned RaggedTensor. padding is a Tensor with the same dtype as tensor and with shape=tensor.shape[ragged_rank + 1:].
  ragged_rank   Integer specifying the ragged rank for the returned RaggedTensor. Must be greater than zero.
  name   A name prefix for the returned tensors (optional).
  row_splits_dtype   dtype for the returned RaggedTensor's row_splits tensor. One of tf.int32 or tf.int64.

 Returns   A RaggedTensor with the specified ragged_rank. The shape of the returned ragged tensor is compatible with the shape of tensor.

 Raises
  ValueError   If both lengths and padding are specified.    from_uniform_row_length View source
@classmethod
from_uniform_row_length(
    values, uniform_row_length, nrows=None, validate=True, name=None
)
 Creates a RaggedTensor with rows partitioned by uniform_row_length. This method can be used to create RaggedTensors with multiple uniform outer dimensions. For example, a RaggedTensor with shape [2, 2, None] can be constructed with this method from a RaggedTensor values with shape [4, None]:
values = tf.ragged.constant([[1, 2, 3], [4], [5, 6], [7, 8, 9, 10]])
print(values.shape)
(4, None)
rt1 = tf.RaggedTensor.from_uniform_row_length(values, 2)
print(rt1)
<tf.RaggedTensor [[[1, 2, 3], [4]], [[5, 6], [7, 8, 9, 10]]]>
print(rt1.shape)
(2, 2, None)
 Note that rt1 only contains one ragged dimension (the innermost dimension). In contrast, if from_row_splits is used to construct a similar RaggedTensor, then that RaggedTensor will have two ragged dimensions:
rt2 = tf.RaggedTensor.from_row_splits(values, [0, 2, 4])
print(rt2.shape)
(2, None, None)

 Args
  values   A potentially ragged tensor with shape [nvals, ...].
  uniform_row_length   A scalar integer tensor. Must be nonnegative. The size of the outer axis of values must be evenly divisible by uniform_row_length.
  nrows   The number of rows in the constructed RaggedTensor. If not specified, then it defaults to nvals/uniform_row_length (or 0 if uniform_row_length==0). nrows only needs to be specified if uniform_row_length might be zero. uniform_row_length*nrows must be nvals.
  validate   If true, then use assertions to check that the arguments form a valid RaggedTensor. Note: these assertions incur a runtime cost, since they must be checked for each tensor value.
  name   A name prefix for the RaggedTensor (optional).

 Returns   A RaggedTensor that corresponds with the python list defined by: result = [[values.pop(0) for i in range(uniform_row_length)]
for _ in range(nrows)]
 result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.

 from_value_rowids View source
@classmethod
from_value_rowids(
    values, value_rowids, nrows=None, name=None, validate=True
)
 Creates a RaggedTensor with rows partitioned by value_rowids. The returned RaggedTensor corresponds with the python list defined by: result = [[values[i] for i in range(len(values)) if value_rowids[i] == row]
          for row in range(nrows)]

 Args
  values   A potentially ragged tensor with shape [nvals, ...].
  value_rowids   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.
  nrows   An integer scalar specifying the number of rows. This should be specified if the RaggedTensor may containing empty training rows. Must be greater than value_rowids[-1] (or zero if value_rowids is empty). Defaults to value_rowids[-1] (or zero if value_rowids is empty).
  name   A name prefix for the RaggedTensor (optional).
  validate   If true, then use assertions to check that the arguments form a valid RaggedTensor. Note: these assertions incur a runtime cost, since they must be checked for each tensor value.

 Returns   A RaggedTensor. result.rank = values.rank + 1. result.ragged_rank = values.ragged_rank + 1.

 Raises
  ValueError   If nrows is incompatible with value_rowids.    Example:
print(tf.RaggedTensor.from_value_rowids(
    values=[3, 1, 4, 1, 5, 9, 2, 6],
    value_rowids=[0, 0, 0, 0, 2, 2, 2, 3],
    nrows=5))
<tf.RaggedTensor [[3, 1, 4, 1], [], [5, 9, 2], [6], []]>
 get_shape View source
get_shape()
 The statically known shape of this ragged tensor.

 Returns   A TensorShape containing the statically known shape of this ragged tensor. Ragged dimensions have a size of None.
 Alias for shape property. Examples:
tf.ragged.constant([[0], [1, 2]]).get_shape()
TensorShape([2, None])

tf.ragged.constant(
   [[[0, 1]], [[1, 2], [3, 4]]], ragged_rank=1).get_shape()
TensorShape([2, None, 2])
 merge_dims View source
merge_dims(
    outer_axis, inner_axis
)
 Merges outer_axis...inner_axis into a single dimension. Returns a copy of this RaggedTensor with the specified range of dimensions flattened into a single dimension, with elements in row-major order. Examples:
rt = tf.ragged.constant([[[1, 2], [3]], [[4, 5, 6]]])
print(rt.merge_dims(0, 1))
<tf.RaggedTensor [[1, 2], [3], [4, 5, 6]]>
print(rt.merge_dims(1, 2))
<tf.RaggedTensor [[1, 2, 3], [4, 5, 6]]>
print(rt.merge_dims(0, 2))
tf.Tensor([1 2 3 4 5 6], shape=(6,), dtype=int32)
 To mimic the behavior of np.flatten (which flattens all dimensions), use rt.merge_dims(0, -1). To mimic the behavior oftf.layers.Flatten(which flattens all dimensions except the outermost batch dimension), usert.merge_dims(1, -1)`.

 Args
  outer_axis   int: The first dimension in the range of dimensions to merge. May be negative if self.shape.rank is statically known.
  inner_axis   int: The last dimension in the range of dimensions to merge. May be negative if self.shape.rank is statically known.

 Returns   A copy of this tensor, with the specified dimensions merged into a single dimension. The shape of the returned tensor will be self.shape[:outer_axis] + [N] + self.shape[inner_axis + 1:], where N is the total number of slices in the merged dimensions.
 nested_row_lengths View source
nested_row_lengths(
    name=None
)
 Returns a tuple containing the row_lengths for all ragged dimensions. rt.nested_row_lengths() is a tuple containing the row_lengths tensors for all ragged dimensions in rt, ordered from outermost to innermost.

 Args
  name   A name prefix for the returned tensors (optional).

 Returns   A tuple of 1-D integer Tensors. The length of the tuple is equal to self.ragged_rank.
 nested_value_rowids View source
nested_value_rowids(
    name=None
)
 Returns a tuple containing the value_rowids for all ragged dimensions. rt.nested_value_rowids is a tuple containing the value_rowids tensors for all ragged dimensions in rt, ordered from outermost to innermost. In particular, rt.nested_value_rowids = (rt.value_rowids(),) + value_ids where: * `value_ids = ()` if `rt.values` is a `Tensor`.
* `value_ids = rt.values.nested_value_rowids` otherwise.

 Args
  name   A name prefix for the returned tensors (optional).

 Returns   A tuple of 1-D integer Tensors.
 Example:
rt = tf.ragged.constant(
    [[[[3, 1, 4, 1], [], [5, 9, 2]], [], [[6], []]]])
for i, ids in enumerate(rt.nested_value_rowids()):
  print('row ids for dimension %d: %s' % (i+1, ids.numpy()))
row ids for dimension 1: [0 0 0]
row ids for dimension 2: [0 0 0 2 2]
row ids for dimension 3: [0 0 0 0 2 2 2 3]
 nrows View source
nrows(
    out_type=None, name=None
)
 Returns the number of rows in this ragged tensor. I.e., the size of the outermost dimension of the tensor.

 Args
  out_type   dtype for the returned tensor. Defaults to self.row_splits.dtype.
  name   A name prefix for the returned tensor (optional).

 Returns   A scalar Tensor with dtype out_type.
 Example:
rt = tf.ragged.constant([[3, 1, 4, 1], [], [5, 9, 2], [6], []])
print(rt.nrows())  # rt has 5 rows.
tf.Tensor(5, shape=(), dtype=int64)
 numpy View source
numpy()
 Returns a numpy array with the values for this RaggedTensor. Requires that this RaggedTensor was constructed in eager execution mode. Ragged dimensions are encoded using numpy arrays with dtype=object and rank=1, where each element is a single row. Examples In the following example, the value returned by RaggedTensor.numpy() contains three numpy array objects: one for each row (with rank=1 and dtype=int64), and one to combine them (with rank=1 and dtype=object):
tf.ragged.constant([[1, 2, 3], [4, 5]], dtype=tf.int64).numpy()
array([array([1, 2, 3]), array([4, 5])], dtype=object)
 Uniform dimensions are encoded using multidimensional numpy arrays. In the following example, the value returned by RaggedTensor.numpy() contains a single numpy array object, with rank=2 and dtype=int64:
tf.ragged.constant([[1, 2, 3], [4, 5, 6]], dtype=tf.int64).numpy()
array([[1, 2, 3], [4, 5, 6]])

 Returns   A numpy array.
 row_lengths View source
row_lengths(
    axis=1, name=None
)
 Returns the lengths of the rows in this ragged tensor. rt.row_lengths()[i] indicates the number of values in the ith row of rt.

 Args
  axis   An integer constant indicating the axis whose row lengths should be returned.
  name   A name prefix for the returned tensor (optional).

 Returns   A potentially ragged integer Tensor with shape self.shape[:axis].

 Raises
  ValueError   If axis is out of bounds.    Example:
rt = tf.ragged.constant(
    [[[3, 1, 4], [1]], [], [[5, 9], [2]], [[6]], []])
print(rt.row_lengths())  # lengths of rows in rt
tf.Tensor([2 0 2 1 0], shape=(5,), dtype=int64)
print(rt.row_lengths(axis=2))  # lengths of axis=2 rows.
<tf.RaggedTensor [[3, 1], [], [2, 1], [1], []]>
 row_limits View source
row_limits(
    name=None
)
 Returns the limit indices for rows in this ragged tensor. These indices specify where the values for each row end in self.values. rt.row_limits(self) is equal to rt.row_splits[:-1].

 Args
  name   A name prefix for the returned tensor (optional).

 Returns   A 1-D integer Tensor with shape [nrows]. The returned tensor is nonnegative, and is sorted in ascending order.
 Example:
rt = tf.ragged.constant([[3, 1, 4, 1], [], [5, 9, 2], [6], []])
print(rt.values)
tf.Tensor([3 1 4 1 5 9 2 6], shape=(8,), dtype=int32)
print(rt.row_limits())  # indices of row limits in rt.values
tf.Tensor([4 4 7 8 8], shape=(5,), dtype=int64)
 row_starts View source
row_starts(
    name=None
)
 Returns the start indices for rows in this ragged tensor. These indices specify where the values for each row begin in self.values. rt.row_starts() is equal to rt.row_splits[:-1].

 Args
  name   A name prefix for the returned tensor (optional).

 Returns   A 1-D integer Tensor with shape [nrows]. The returned tensor is nonnegative, and is sorted in ascending order.
 Example:
rt = tf.ragged.constant([[3, 1, 4, 1], [], [5, 9, 2], [6], []])
print(rt.values)
tf.Tensor([3 1 4 1 5 9 2 6], shape=(8,), dtype=int32)
print(rt.row_starts())  # indices of row starts in rt.values
tf.Tensor([0 4 4 7 8], shape=(5,), dtype=int64)
 to_list View source
to_list()
 Returns a nested Python list with the values for this RaggedTensor. Requires that rt was constructed in eager execution mode.

 Returns   A nested Python list.
 to_sparse View source
to_sparse(
    name=None
)
 Converts this RaggedTensor into a tf.sparse.SparseTensor. Example:
rt = tf.ragged.constant([[1, 2, 3], [4], [], [5, 6]])
print(rt.to_sparse())
SparseTensor(indices=tf.Tensor(
                 [[0 0] [0 1] [0 2] [1 0] [3 0] [3 1]],
                 shape=(6, 2), dtype=int64),
             values=tf.Tensor([1 2 3 4 5 6], shape=(6,), dtype=int32),
             dense_shape=tf.Tensor([4 3], shape=(2,), dtype=int64))

 Args
  name   A name prefix for the returned tensors (optional).

 Returns   A SparseTensor with the same values as self.
 to_tensor View source
to_tensor(
    default_value=None, name=None, shape=None
)
 Converts this RaggedTensor into a tf.Tensor. If shape is specified, then the result is padded and/or truncated to the specified shape. Examples:
rt = tf.ragged.constant([[9, 8, 7], [], [6, 5], [4]])
print(rt.to_tensor())
tf.Tensor(
    [[9 8 7] [0 0 0] [6 5 0] [4 0 0]], shape=(4, 3), dtype=int32)
print(rt.to_tensor(shape=[5, 2]))
tf.Tensor(
    [[9 8] [0 0] [6 5] [4 0] [0 0]], shape=(5, 2), dtype=int32)

 Args
  default_value   Value to set for indices not specified in self. Defaults to zero. default_value must be broadcastable to self.shape[self.ragged_rank + 1:].
  name   A name prefix for the returned tensors (optional).
  shape   The shape of the resulting dense tensor. In particular, result.shape[i] is shape[i] (if shape[i] is not None), or self.bounding_shape(i) (otherwise).shape.rank must be None or equal to self.rank.

 Returns   A Tensor with shape ragged.bounding_shape(self) and the values specified by the non-empty values in self. Empty values are assigned default_value.
 value_rowids View source
value_rowids(
    name=None
)
 Returns the row indices for the values in this ragged tensor. rt.value_rowids() corresponds one-to-one with the outermost dimension of rt.values, and specifies the row containing each value. In particular, the row rt[row] consists of the values rt.values[j] where rt.value_rowids()[j] == row.

 Args
  name   A name prefix for the returned tensor (optional).

 Returns   A 1-D integer Tensor with shape self.values.shape[:1]. The returned tensor is nonnegative, and is sorted in ascending order.
 Example:
rt = tf.ragged.constant([[3, 1, 4, 1], [], [5, 9, 2], [6], []])
print(rt.values)
tf.Tensor([3 1 4 1 5 9 2 6], shape=(8,), dtype=int32)
print(rt.value_rowids())  # corresponds 1:1 with rt.values
tf.Tensor([0 0 0 0 2 2 2 3], shape=(8,), dtype=int64)
 with_flat_values View source
with_flat_values(
    new_values
)
 Returns a copy of self with flat_values replaced by new_value. Preserves cached row-partitioning tensors such as self.cached_nrows and self.cached_value_rowids if they have values.

 Args
  new_values   Potentially ragged tensor that should replace self.flat_values. Must have rank > 0, and must have the same number of rows as self.flat_values.

 Returns   A RaggedTensor. result.rank = self.ragged_rank + new_values.rank. result.ragged_rank = self.ragged_rank + new_values.ragged_rank.
 with_row_splits_dtype View source
with_row_splits_dtype(
    dtype
)
 Returns a copy of this RaggedTensor with the given row_splits dtype. For RaggedTensors with multiple ragged dimensions, the row_splits for all nested RaggedTensor objects are cast to the given dtype.

 Args
  dtype   The dtype for row_splits. One of tf.int32 or tf.int64.

 Returns   A copy of this RaggedTensor, with the row_splits cast to the given type.
 with_values View source
with_values(
    new_values
)
 Returns a copy of self with values replaced by new_value. Preserves cached row-partitioning tensors such as self.cached_nrows and self.cached_value_rowids if they have values.

 Args
  new_values   Potentially ragged tensor to use as the values for the returned RaggedTensor. Must have rank > 0, and must have the same number of rows as self.values.

 Returns   A RaggedTensor. result.rank = 1 + new_values.rank. result.ragged_rank = 1 + new_values.ragged_rank
 __abs__ View source
__abs__(
    x, name=None
)
 Computes the absolute value of a tensor. Given a tensor of integer or floating-point values, this operation returns a tensor of the same type, where each element contains the absolute value of the corresponding element in the input. Given a tensor x of complex numbers, this operation returns a tensor of type float32 or float64 that is the absolute value of each element in x. For a complex number \(a + bj\), its absolute value is computed as \(\sqrt{a^2 + b^2}\). For example:
# real number
x = tf.constant([-2.25, 3.25])
tf.abs(x)
<tf.Tensor: shape=(2,), dtype=float32,
numpy=array([2.25, 3.25], dtype=float32)>

# complex number
x = tf.constant([[-2.25 + 4.75j], [-3.25 + 5.75j]])
tf.abs(x)
<tf.Tensor: shape=(2, 1), dtype=float64, numpy=
array([[5.25594901],
       [6.60492241]])>

 Args
  x   A Tensor or SparseTensor of type float16, float32, float64, int32, int64, complex64 or complex128.
  name   A name for the operation (optional).

 Returns   A Tensor or SparseTensor of the same size, type and sparsity as x, with absolute values. Note, for complex64 or complex128 input, the returned Tensor will be of type float32 or float64, respectively. If x is a SparseTensor, returns SparseTensor(x.indices, tf.math.abs(x.values, ...), x.dense_shape)

 __add__
__add__(
    x, y, name=None
)
 Returns x + y element-wise.
Note: math.add supports broadcasting. AddN does not. More about broadcasting here
 Given two input tensors, the tf.add operation computes the sum for every element in the tensor. Both input and output have a range (-inf, inf).

 Args
  x   A Tensor. Must be one of the following types: bfloat16, half, float32, float64, uint8, int8, int16, int32, int64, complex64, complex128, string.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns   A Tensor. Has the same type as x.
 __and__ View source
__and__(
    x, y, name=None
)
 Logical AND function. The operation works for the following input types:  Two single elements of type bool
 One tf.Tensor of type bool and one single bool, where the result will be calculated by applying logical AND with the single element to each element in the larger Tensor. Two tf.Tensor objects of type bool of the same shape. In this case, the result will be the element-wise logical AND of the two input tensors.  Usage:
a = tf.constant([True])
b = tf.constant([False])
tf.math.logical_and(a, b)
<tf.Tensor: shape=(1,), dtype=bool, numpy=array([False])>

c = tf.constant([True])
x = tf.constant([False, True, True, False])
tf.math.logical_and(c, x)
<tf.Tensor: shape=(4,), dtype=bool, numpy=array([False,  True,  True, False])>

y = tf.constant([False, False, True, True])
z = tf.constant([False, True, False, True])
tf.math.logical_and(y, z)
<tf.Tensor: shape=(4,), dtype=bool, numpy=array([False, False, False,  True])>

 Args
  x   A tf.Tensor type bool.
  y   A tf.Tensor of type bool.
  name   A name for the operation (optional).

 Returns   A tf.Tensor of type bool with the same size as that of x or y.
 __bool__ View source
__bool__(
    _
)
 Dummy method to prevent a RaggedTensor from being used as a Python bool. __div__ View source
__div__(
    x, y, name=None
)
 Divides x / y elementwise (using Python 2 division operator semantics). (deprecated) Warning: THIS FUNCTION IS DEPRECATED. It will be removed in a future version. Instructions for updating: Deprecated in favor of operator or tf.math.divide.
Note: Prefer using the Tensor division operator or tf.divide which obey Python 3 division operator semantics.
 This function divides x and y, forcing Python 2 semantics. That is, if x and y are both integers then the result will be an integer. This is in contrast to Python 3, where division with / is always a float while division with // is always an integer.

 Args
  x   Tensor numerator of real numeric type.
  y   Tensor denominator of real numeric type.
  name   A name for the operation (optional).

 Returns   x / y returns the quotient of x and y.
 __eq__ View source
__eq__(
    other
)
 The operation invoked by the Tensor.eq operator. Compares two tensors element-wise for equality if they are broadcast-compatible; or returns False if they are not broadcast-compatible. (Note that this behavior differs from tf.math.equal, which raises an exception if the two tensors are not broadcast-compatible.) Purpose in the API: This method is exposed in TensorFlow's API so that library developers can register dispatching for Tensor.eq to allow it to handle custom composite tensors & other custom objects. The API symbol is not intended to be called by users directly and does appear in TensorFlow's generated documentation.

 Args
  self   The left-hand side of the == operator.
  other   The right-hand side of the == operator.

 Returns   The result of the elementwise == operation, or False if the arguments are not broadcast-compatible.
 __floordiv__ View source
__floordiv__(
    x, y, name=None
)
 Divides x / y elementwise, rounding toward the most negative integer. The same as tf.compat.v1.div(x,y) for integers, but uses tf.floor(tf.compat.v1.div(x,y)) for floating point arguments so that the result is always an integer (though possibly an integer represented as floating point). This op is generated by x // y floor division in Python 3 and in Python 2.7 with from __future__ import division. x and y must have the same type, and the result will have the same type as well.

 Args
  x   Tensor numerator of real numeric type.
  y   Tensor denominator of real numeric type.
  name   A name for the operation (optional).

 Returns   x / y rounded down.

 Raises
  TypeError   If the inputs are complex.    __ge__
__ge__(
    x, y, name=None
)
 Returns the truth value of (x >= y) element-wise.
Note: math.greater_equal supports broadcasting. More about broadcasting here
 Example: x = tf.constant([5, 4, 6, 7])
y = tf.constant([5, 2, 5, 10])
tf.math.greater_equal(x, y) ==> [True, True, True, False]

x = tf.constant([5, 4, 6, 7])
y = tf.constant([5])
tf.math.greater_equal(x, y) ==> [True, False, True, True]

 Args
  x   A Tensor. Must be one of the following types: float32, float64, int32, uint8, int16, int8, int64, bfloat16, uint16, half, uint32, uint64.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns   A Tensor of type bool.
 __getitem__ View source
__getitem__(
    key
)
 Returns the specified piece of this RaggedTensor. Supports multidimensional indexing and slicing, with one restriction: indexing into a ragged inner dimension is not allowed. This case is problematic because the indicated value may exist in some rows but not others. In such cases, it's not obvious whether we should (1) report an IndexError; (2) use a default value; or (3) skip that value and return a tensor with fewer rows than we started with. Following the guiding principles of Python ("In the face of ambiguity, refuse the temptation to guess"), we simply disallow this operation.

 Args
  self   The RaggedTensor to slice.
  key   Indicates which piece of the RaggedTensor to return, using standard Python semantics (e.g., negative values index from the end). key may have any of the following types:
int constant Scalar integer Tensor

slice containing integer constants and/or scalar integer Tensors Ellipsis tf.newaxis
tuple containing any of the above (for multidimensional indexing)

 Returns   A Tensor or RaggedTensor object. Values that include at least one ragged dimension are returned as RaggedTensor. Values that include no ragged dimensions are returned as Tensor. See above for examples of expressions that return Tensors vs RaggedTensors.

 Raises
  ValueError   If key is out of bounds.
  ValueError   If key is not supported.
  TypeError   If the indices in key have an unsupported type.    Examples:
# A 2-D ragged tensor with 1 ragged dimension.
rt = tf.ragged.constant([['a', 'b', 'c'], ['d', 'e'], ['f'], ['g']])
rt[0].numpy()                 # First row (1-D `Tensor`)
array([b'a', b'b', b'c'], dtype=object)
rt[:3].to_list()              # First three rows (2-D RaggedTensor)
[[b'a', b'b', b'c'], [b'd', b'e'], [b'f']]
rt[3, 0].numpy()              # 1st element of 4th row (scalar)
b'g'

# A 3-D ragged tensor with 2 ragged dimensions.
rt = tf.ragged.constant([[[1, 2, 3], [4]],
                         [[5], [], [6]],
                         [[7]],
                         [[8, 9], [10]]])
rt[1].to_list()               # Second row (2-D RaggedTensor)
[[5], [], [6]]
rt[3, 0].numpy()              # First element of fourth row (1-D Tensor)
array([8, 9], dtype=int32)
rt[:, 1:3].to_list()          # Items 1-3 of each row (3-D RaggedTensor)
[[[4]], [[], [6]], [], [[10]]]
rt[:, -1:].to_list()          # Last item of each row (3-D RaggedTensor)
[[[4]], [[6]], [[7]], [[10]]]
 __gt__
__gt__(
    x, y, name=None
)
 Returns the truth value of (x > y) element-wise.
Note: math.greater supports broadcasting. More about broadcasting here
 Example: x = tf.constant([5, 4, 6])
y = tf.constant([5, 2, 5])
tf.math.greater(x, y) ==> [False, True, True]

x = tf.constant([5, 4, 6])
y = tf.constant([5])
tf.math.greater(x, y) ==> [False, False, True]

 Args
  x   A Tensor. Must be one of the following types: float32, float64, int32, uint8, int16, int8, int64, bfloat16, uint16, half, uint32, uint64.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns   A Tensor of type bool.
 __invert__
__invert__(
    x, name=None
)
 Returns the truth value of NOT x element-wise. Example:
tf.math.logical_not(tf.constant([True, False]))
<tf.Tensor: shape=(2,), dtype=bool, numpy=array([False,  True])>

 Args
  x   A Tensor of type bool. A Tensor of type bool.
  name   A name for the operation (optional).

 Returns   A Tensor of type bool.
 __le__
__le__(
    x, y, name=None
)
 Returns the truth value of (x <= y) element-wise.
Note: math.less_equal supports broadcasting. More about broadcasting here
 Example: x = tf.constant([5, 4, 6])
y = tf.constant([5])
tf.math.less_equal(x, y) ==> [True, True, False]

x = tf.constant([5, 4, 6])
y = tf.constant([5, 6, 6])
tf.math.less_equal(x, y) ==> [True, True, True]

 Args
  x   A Tensor. Must be one of the following types: float32, float64, int32, uint8, int16, int8, int64, bfloat16, uint16, half, uint32, uint64.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns   A Tensor of type bool.
 __lt__
__lt__(
    x, y, name=None
)
 Returns the truth value of (x < y) element-wise.
Note: math.less supports broadcasting. More about broadcasting here
 Example: x = tf.constant([5, 4, 6])
y = tf.constant([5])
tf.math.less(x, y) ==> [False, True, False]

x = tf.constant([5, 4, 6])
y = tf.constant([5, 6, 7])
tf.math.less(x, y) ==> [False, True, True]

 Args
  x   A Tensor. Must be one of the following types: float32, float64, int32, uint8, int16, int8, int64, bfloat16, uint16, half, uint32, uint64.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns   A Tensor of type bool.
 __mod__
__mod__(
    x, y, name=None
)
 Returns element-wise remainder of division. When x < 0 xor y < 0 is true, this follows Python semantics in that the result here is consistent with a flooring divide. E.g. floor(x / y) * y + mod(x, y) = x.
Note: math.floormod supports broadcasting. More about broadcasting here

 Args
  x   A Tensor. Must be one of the following types: int32, int64, uint64, bfloat16, half, float32, float64.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns   A Tensor. Has the same type as x.
 __mul__ View source
__mul__(
    x, y, name=None
)
 Returns an element-wise x * y. For example:
x = tf.constant(([1, 2, 3, 4]))
tf.math.multiply(x, x)
<tf.Tensor: shape=(4,), dtype=..., numpy=array([ 1,  4,  9, 16], dtype=int32)>
 Since tf.math.multiply will convert its arguments to Tensors, you can also pass in non-Tensor arguments:
tf.math.multiply(7,6)
<tf.Tensor: shape=(), dtype=int32, numpy=42>
 If x.shape is not thes same as y.shape, they will be broadcast to a compatible shape. (More about broadcasting here.) For example:
x = tf.ones([1, 2]);
y = tf.ones([2, 1]);
x * y  # Taking advantage of operator overriding
<tf.Tensor: shape=(2, 2), dtype=float32, numpy=
array([[1., 1.],
     [1., 1.]], dtype=float32)>

 Args
  x   A Tensor. Must be one of the following types: bfloat16, half, float32, float64, uint8, int8, uint16, int16, int32, int64, complex64, complex128.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns
 A Tensor. Has the same type as x.

 Raises    InvalidArgumentError: When x and y have incomptatible shapes or types.

 __ne__ View source
__ne__(
    other
)
 The operation invoked by the Tensor.ne operator. Compares two tensors element-wise for inequality if they are broadcast-compatible; or returns True if they are not broadcast-compatible. (Note that this behavior differs from tf.math.not_equal, which raises an exception if the two tensors are not broadcast-compatible.) Purpose in the API: This method is exposed in TensorFlow's API so that library developers can register dispatching for Tensor.ne to allow it to handle custom composite tensors & other custom objects. The API symbol is not intended to be called by users directly and does appear in TensorFlow's generated documentation.

 Args
  self   The left-hand side of the != operator.
  other   The right-hand side of the != operator.

 Returns   The result of the elementwise != operation, or True if the arguments are not broadcast-compatible.
 __neg__
__neg__(
    x, name=None
)
 Computes numerical negative value element-wise. I.e., \(y = -x\).

 Args
  x   A Tensor. Must be one of the following types: bfloat16, half, float32, float64, int8, int16, int32, int64, complex64, complex128.
  name   A name for the operation (optional).

 Returns   A Tensor. Has the same type as x. If x is a SparseTensor, returns SparseTensor(x.indices, tf.math.negative(x.values, ...), x.dense_shape)

 __nonzero__ View source
__nonzero__(
    _
)
 Dummy method to prevent a RaggedTensor from being used as a Python bool. __or__
__or__(
    x, y, name=None
)
 Returns the truth value of x OR y element-wise.
Note: math.logical_or supports broadcasting. More about broadcasting here

 Args
  x   A Tensor of type bool.
  y   A Tensor of type bool.
  name   A name for the operation (optional).

 Returns   A Tensor of type bool.
 __pow__ View source
__pow__(
    x, y, name=None
)
 Computes the power of one value to another. Given a tensor x and a tensor y, this operation computes \(x^y\) for corresponding elements in x and y. For example: x = tf.constant([[2, 2], [3, 3]])
y = tf.constant([[8, 16], [2, 3]])
tf.pow(x, y)  # [[256, 65536], [9, 27]]

 Args
  x   A Tensor of type float16, float32, float64, int32, int64, complex64, or complex128.
  y   A Tensor of type float16, float32, float64, int32, int64, complex64, or complex128.
  name   A name for the operation (optional).

 Returns   A Tensor.
 __radd__
__radd__(
    x, y, name=None
)
 Returns x + y element-wise.
Note: math.add supports broadcasting. AddN does not. More about broadcasting here
 Given two input tensors, the tf.add operation computes the sum for every element in the tensor. Both input and output have a range (-inf, inf).

 Args
  x   A Tensor. Must be one of the following types: bfloat16, half, float32, float64, uint8, int8, int16, int32, int64, complex64, complex128, string.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns   A Tensor. Has the same type as x.
 __rand__ View source
__rand__(
    x, y, name=None
)
 Logical AND function. The operation works for the following input types:  Two single elements of type bool
 One tf.Tensor of type bool and one single bool, where the result will be calculated by applying logical AND with the single element to each element in the larger Tensor. Two tf.Tensor objects of type bool of the same shape. In this case, the result will be the element-wise logical AND of the two input tensors.  Usage:
a = tf.constant([True])
b = tf.constant([False])
tf.math.logical_and(a, b)
<tf.Tensor: shape=(1,), dtype=bool, numpy=array([False])>

c = tf.constant([True])
x = tf.constant([False, True, True, False])
tf.math.logical_and(c, x)
<tf.Tensor: shape=(4,), dtype=bool, numpy=array([False,  True,  True, False])>

y = tf.constant([False, False, True, True])
z = tf.constant([False, True, False, True])
tf.math.logical_and(y, z)
<tf.Tensor: shape=(4,), dtype=bool, numpy=array([False, False, False,  True])>

 Args
  x   A tf.Tensor type bool.
  y   A tf.Tensor of type bool.
  name   A name for the operation (optional).

 Returns   A tf.Tensor of type bool with the same size as that of x or y.
 __rdiv__ View source
__rdiv__(
    x, y, name=None
)
 Divides x / y elementwise (using Python 2 division operator semantics). (deprecated) Warning: THIS FUNCTION IS DEPRECATED. It will be removed in a future version. Instructions for updating: Deprecated in favor of operator or tf.math.divide.
Note: Prefer using the Tensor division operator or tf.divide which obey Python 3 division operator semantics.
 This function divides x and y, forcing Python 2 semantics. That is, if x and y are both integers then the result will be an integer. This is in contrast to Python 3, where division with / is always a float while division with // is always an integer.

 Args
  x   Tensor numerator of real numeric type.
  y   Tensor denominator of real numeric type.
  name   A name for the operation (optional).

 Returns   x / y returns the quotient of x and y.
 __rfloordiv__ View source
__rfloordiv__(
    x, y, name=None
)
 Divides x / y elementwise, rounding toward the most negative integer. The same as tf.compat.v1.div(x,y) for integers, but uses tf.floor(tf.compat.v1.div(x,y)) for floating point arguments so that the result is always an integer (though possibly an integer represented as floating point). This op is generated by x // y floor division in Python 3 and in Python 2.7 with from __future__ import division. x and y must have the same type, and the result will have the same type as well.

 Args
  x   Tensor numerator of real numeric type.
  y   Tensor denominator of real numeric type.
  name   A name for the operation (optional).

 Returns   x / y rounded down.

 Raises
  TypeError   If the inputs are complex.    __rmod__
__rmod__(
    x, y, name=None
)
 Returns element-wise remainder of division. When x < 0 xor y < 0 is true, this follows Python semantics in that the result here is consistent with a flooring divide. E.g. floor(x / y) * y + mod(x, y) = x.
Note: math.floormod supports broadcasting. More about broadcasting here

 Args
  x   A Tensor. Must be one of the following types: int32, int64, uint64, bfloat16, half, float32, float64.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns   A Tensor. Has the same type as x.
 __rmul__ View source
__rmul__(
    x, y, name=None
)
 Returns an element-wise x * y. For example:
x = tf.constant(([1, 2, 3, 4]))
tf.math.multiply(x, x)
<tf.Tensor: shape=(4,), dtype=..., numpy=array([ 1,  4,  9, 16], dtype=int32)>
 Since tf.math.multiply will convert its arguments to Tensors, you can also pass in non-Tensor arguments:
tf.math.multiply(7,6)
<tf.Tensor: shape=(), dtype=int32, numpy=42>
 If x.shape is not thes same as y.shape, they will be broadcast to a compatible shape. (More about broadcasting here.) For example:
x = tf.ones([1, 2]);
y = tf.ones([2, 1]);
x * y  # Taking advantage of operator overriding
<tf.Tensor: shape=(2, 2), dtype=float32, numpy=
array([[1., 1.],
     [1., 1.]], dtype=float32)>

 Args
  x   A Tensor. Must be one of the following types: bfloat16, half, float32, float64, uint8, int8, uint16, int16, int32, int64, complex64, complex128.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns
 A Tensor. Has the same type as x.

 Raises    InvalidArgumentError: When x and y have incomptatible shapes or types.

 __ror__
__ror__(
    x, y, name=None
)
 Returns the truth value of x OR y element-wise.
Note: math.logical_or supports broadcasting. More about broadcasting here

 Args
  x   A Tensor of type bool.
  y   A Tensor of type bool.
  name   A name for the operation (optional).

 Returns   A Tensor of type bool.
 __rpow__ View source
__rpow__(
    x, y, name=None
)
 Computes the power of one value to another. Given a tensor x and a tensor y, this operation computes \(x^y\) for corresponding elements in x and y. For example: x = tf.constant([[2, 2], [3, 3]])
y = tf.constant([[8, 16], [2, 3]])
tf.pow(x, y)  # [[256, 65536], [9, 27]]

 Args
  x   A Tensor of type float16, float32, float64, int32, int64, complex64, or complex128.
  y   A Tensor of type float16, float32, float64, int32, int64, complex64, or complex128.
  name   A name for the operation (optional).

 Returns   A Tensor.
 __rsub__ View source
__rsub__(
    x, y, name=None
)
 Returns x - y element-wise.
Note: Subtract supports broadcasting. More about broadcasting here

 Args
  x   A Tensor. Must be one of the following types: bfloat16, half, float32, float64, uint8, int8, uint16, int16, int32, int64, complex64, complex128, uint32.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns   A Tensor. Has the same type as x.
 __rtruediv__ View source
__rtruediv__(
    x, y, name=None
)
 Divides x / y elementwise (using Python 3 division operator semantics).
Note: Prefer using the Tensor operator or tf.divide which obey Python division operator semantics.
 This function forces Python 3 division operator semantics where all integer arguments are cast to floating types first. This op is generated by normal x / y division in Python 3 and in Python 2.7 with from __future__ import division. If you want integer division that rounds down, use x // y or tf.math.floordiv. x and y must have the same numeric type. If the inputs are floating point, the output will have the same type. If the inputs are integral, the inputs are cast to float32 for int8 and int16 and float64 for int32 and int64 (matching the behavior of Numpy).

 Args
  x   Tensor numerator of numeric type.
  y   Tensor denominator of numeric type.
  name   A name for the operation (optional).

 Returns   x / y evaluated in floating point.

 Raises
  TypeError   If x and y have different dtypes.    __rxor__ View source
__rxor__(
    x, y, name='LogicalXor'
)
 Logical XOR function. x ^ y = (x | y) & ~(x & y) The operation works for the following input types:  Two single elements of type bool
 One tf.Tensor of type bool and one single bool, where the result will be calculated by applying logical XOR with the single element to each element in the larger Tensor. Two tf.Tensor objects of type bool of the same shape. In this case, the result will be the element-wise logical XOR of the two input tensors.  Usage:
a = tf.constant([True])
b = tf.constant([False])
tf.math.logical_xor(a, b)
<tf.Tensor: shape=(1,), dtype=bool, numpy=array([ True])>

c = tf.constant([True])
x = tf.constant([False, True, True, False])
tf.math.logical_xor(c, x)
<tf.Tensor: shape=(4,), dtype=bool, numpy=array([ True, False, False,  True])>

y = tf.constant([False, False, True, True])
z = tf.constant([False, True, False, True])
tf.math.logical_xor(y, z)
<tf.Tensor: shape=(4,), dtype=bool, numpy=array([False,  True,  True, False])>

 Args
  x   A tf.Tensor type bool.
  y   A tf.Tensor of type bool.
  name   A name for the operation (optional).

 Returns   A tf.Tensor of type bool with the same size as that of x or y.
 __sub__ View source
__sub__(
    x, y, name=None
)
 Returns x - y element-wise.
Note: Subtract supports broadcasting. More about broadcasting here

 Args
  x   A Tensor. Must be one of the following types: bfloat16, half, float32, float64, uint8, int8, uint16, int16, int32, int64, complex64, complex128, uint32.
  y   A Tensor. Must have the same type as x.
  name   A name for the operation (optional).

 Returns   A Tensor. Has the same type as x.
 __truediv__ View source
__truediv__(
    x, y, name=None
)
 Divides x / y elementwise (using Python 3 division operator semantics).
Note: Prefer using the Tensor operator or tf.divide which obey Python division operator semantics.
 This function forces Python 3 division operator semantics where all integer arguments are cast to floating types first. This op is generated by normal x / y division in Python 3 and in Python 2.7 with from __future__ import division. If you want integer division that rounds down, use x // y or tf.math.floordiv. x and y must have the same numeric type. If the inputs are floating point, the output will have the same type. If the inputs are integral, the inputs are cast to float32 for int8 and int16 and float64 for int32 and int64 (matching the behavior of Numpy).

 Args
  x   Tensor numerator of numeric type.
  y   Tensor denominator of numeric type.
  name   A name for the operation (optional).

 Returns   x / y evaluated in floating point.

 Raises
  TypeError   If x and y have different dtypes.    __xor__ View source
__xor__(
    x, y, name='LogicalXor'
)
 Logical XOR function. x ^ y = (x | y) & ~(x & y) The operation works for the following input types:  Two single elements of type bool
 One tf.Tensor of type bool and one single bool, where the result will be calculated by applying logical XOR with the single element to each element in the larger Tensor. Two tf.Tensor objects of type bool of the same shape. In this case, the result will be the element-wise logical XOR of the two input tensors.  Usage:
a = tf.constant([True])
b = tf.constant([False])
tf.math.logical_xor(a, b)
<tf.Tensor: shape=(1,), dtype=bool, numpy=array([ True])>

c = tf.constant([True])
x = tf.constant([False, True, True, False])
tf.math.logical_xor(c, x)
<tf.Tensor: shape=(4,), dtype=bool, numpy=array([ True, False, False,  True])>

y = tf.constant([False, False, True, True])
z = tf.constant([False, True, False, True])
tf.math.logical_xor(y, z)
<tf.Tensor: shape=(4,), dtype=bool, numpy=array([False,  True,  True, False])>

 Args
  x   A tf.Tensor type bool.
  y   A tf.Tensor of type bool.
  name   A name for the operation (optional).

 Returns   A tf.Tensor of type bool with the same size as that of x or y.


tf.RaggedTensorSpec     View source on GitHub    Type specification for a tf.RaggedTensor. Inherits From: TypeSpec  View aliases  Compat aliases for migration
See Migration guide for more details. tf.compat.v1.RaggedTensorSpec
tf.RaggedTensorSpec(
    shape=None, dtype=tf.dtypes.float32, ragged_rank=None,
    row_splits_dtype=tf.dtypes.int64, flat_values_spec=None
)

 Args
  shape   The shape of the RaggedTensor, or None to allow any shape. If a shape is specified, then all ragged dimensions must have size None.
  dtype   tf.DType of values in the RaggedTensor.
  ragged_rank   Python integer, the number of times the RaggedTensor's flat_values is partitioned. Defaults to shape.ndims - 1.
  row_splits_dtype   dtype for the RaggedTensor's row_splits tensor. One of tf.int32 or tf.int64.
  flat_values_spec   TypeSpec for flat_value of the RaggedTensor. It shall be provided when the flat_values is a CompositeTensor rather then Tensor. If both dtype and flat_values_spec and are provided, dtype must be the same as flat_values_spec.dtype. (experimental)

 Attributes
  dtype   The tf.dtypes.DType specified by this type for the RaggedTensor.
rt = tf.ragged.constant([["a"], ["b", "c"]], dtype=tf.string)
tf.type_spec_from_value(rt).dtype
tf.string

  flat_values_spec   The TypeSpec of the flat_values of RaggedTensor.
  ragged_rank   The number of times the RaggedTensor's flat_values is partitioned. Defaults to shape.ndims - 1.
values = tf.ragged.constant([[1, 2, 3], [4], [5, 6], [7, 8, 9, 10]])
tf.type_spec_from_value(values).ragged_rank
1

rt1 = tf.RaggedTensor.from_uniform_row_length(values, 2)
tf.type_spec_from_value(rt1).ragged_rank
2

  row_splits_dtype   The tf.dtypes.DType of the RaggedTensor's row_splits.
rt = tf.ragged.constant([[1, 2, 3], [4]], row_splits_dtype=tf.int64)
tf.type_spec_from_value(rt).row_splits_dtype
tf.int64

  shape   The statically known shape of the RaggedTensor.
rt = tf.ragged.constant([[0], [1, 2]])
tf.type_spec_from_value(rt).shape
TensorShape([2, None])

rt = tf.ragged.constant([[[0, 1]], [[1, 2], [3, 4]]], ragged_rank=1)
tf.type_spec_from_value(rt).shape
TensorShape([2, None, 2])

  value_type   The Python type for values that are compatible with this TypeSpec. In particular, all values that are compatible with this TypeSpec must be an instance of this type.
   Methods from_value View source
@classmethod
from_value(
    value
)
 is_compatible_with View source
is_compatible_with(
    spec_or_value
)
 Returns true if spec_or_value is compatible with this TypeSpec. most_specific_compatible_type View source
most_specific_compatible_type(
    other
)
 Returns the most specific TypeSpec compatible with self and other.

 Args
  other   A TypeSpec.

 Raises
  ValueError   If there is no TypeSpec that is compatible with both self and other.    __eq__ View source
__eq__(
    other
)
 Return self==value. __ne__ View source
__ne__(
    other
)
 Return self!=value.


Module: tf.random Public API for tf.random namespace. Modules experimental module: Public API for tf.random.experimental namespace. Classes class Algorithm: An enumeration. class Generator: Random-number generator. Functions all_candidate_sampler(...): Generate the set of all classes. categorical(...): Draws samples from a categorical distribution. create_rng_state(...): Creates a RNG state from an integer or a vector. fixed_unigram_candidate_sampler(...): Samples a set of classes using the provided (fixed) base distribution. gamma(...): Draws shape samples from each of the given Gamma distribution(s). get_global_generator(...): Retrieves the global generator. learned_unigram_candidate_sampler(...): Samples a set of classes from a distribution learned during training. log_uniform_candidate_sampler(...): Samples a set of classes using a log-uniform (Zipfian) base distribution. normal(...): Outputs random values from a normal distribution. poisson(...): Draws shape samples from each of the given Poisson distribution(s). set_global_generator(...): Replaces the global generator with another Generator object. set_seed(...): Sets the global random seed. shuffle(...): Randomly shuffles a tensor along its first dimension. stateless_binomial(...): Outputs deterministic pseudorandom values from a binomial distribution. stateless_categorical(...): Draws deterministic pseudorandom samples from a categorical distribution. stateless_gamma(...): Outputs deterministic pseudorandom values from a gamma distribution. stateless_normal(...): Outputs deterministic pseudorandom values from a normal distribution. stateless_parameterized_truncated_normal(...): Outputs random values from a truncated normal distribution. stateless_poisson(...): Outputs deterministic pseudorandom values from a Poisson distribution. stateless_truncated_normal(...): Outputs deterministic pseudorandom values, truncated normally distributed. stateless_uniform(...): Outputs deterministic pseudorandom values from a uniform distribution. truncated_normal(...): Outputs random values from a truncated normal distribution. uniform(...): Outputs random values from a uniform distribution. uniform_candidate_sampler(...): Samples a set of classes using a uniform base distribution.


tf.random.Algorithm An enumeration.  View aliases  Main aliases
tf.random.experimental.Algorithm Compat aliases for migration See Migration guide for more details. tf.compat.v1.random.Algorithm, tf.compat.v1.random.experimental.Algorithm

 Class Variables
  PHILOX   tf.random.Algorithm
  THREEFRY   tf.random.Algorithm


tf.random.all_candidate_sampler     View source on GitHub    Generate the set of all classes.  View aliases  Main aliases
tf.nn.all_candidate_sampler Compat aliases for migration See Migration guide for more details. tf.compat.v1.nn.all_candidate_sampler, tf.compat.v1.random.all_candidate_sampler
tf.random.all_candidate_sampler(
    true_classes, num_true, num_sampled, unique, seed=None, name=None
)
 Deterministically generates and returns the set of all possible classes. For testing purposes. There is no need to use this, since you might as well use full softmax or full logistic regression.

 Args
  true_classes   A Tensor of type int64 and shape [batch_size, num_true]. The target classes.
  num_true   An int. The number of target classes per training example.
  num_sampled   An int. The number of possible classes.
  unique   A bool. Ignored. unique.
  seed   An int. An operation-specific seed. Default is 0.
  name   A name for the operation (optional).

 Returns
  sampled_candidates   A tensor of type int64 and shape [num_sampled]. This operation deterministically returns the entire range [0, num_sampled].
  true_expected_count   A tensor of type float. Same shape as true_classes. The expected counts under the sampling distribution of each of true_classes. All returned values are 1.0.
  sampled_expected_count   A tensor of type float. Same shape as sampled_candidates. The expected counts under the sampling distribution of each of sampled_candidates. All returned values are 1.0.


tf.random.categorical     View source on GitHub    Draws samples from a categorical distribution.  View aliases  Compat aliases for migration
See Migration guide for more details. tf.compat.v1.random.categorical
tf.random.categorical(
    logits, num_samples, dtype=None, seed=None, name=None
)
 Example: # samples has shape [1, 5], where each value is either 0 or 1 with equal
# probability.
samples = tf.random.categorical(tf.math.log([[0.5, 0.5]]), 5)

 Args
  logits   2-D Tensor with shape [batch_size, num_classes]. Each slice [i, :] represents the unnormalized log-probabilities for all classes.
  num_samples   0-D. Number of independent samples to draw for each row slice.
  dtype   integer type to use for the output. Defaults to int64.
  seed   A Python integer. Used to create a random seed for the distribution. See tf.random.set_seed for behavior.
  name   Optional name for the operation.

 Returns   The drawn samples of shape [batch_size, num_samples].


tf.random.create_rng_state Creates a RNG state from an integer or a vector.  View aliases  Main aliases
tf.random.experimental.create_rng_state Compat aliases for migration See Migration guide for more details. tf.compat.v1.random.create_rng_state, tf.compat.v1.random.experimental.create_rng_state
tf.random.create_rng_state(
    seed, alg
)
 Example:
tf.random.create_rng_state(
    1234, "philox")
array([1234,    0,    0])
tf.random.create_rng_state(
    [12, 34], "threefry")
array([12, 34])

 Args
  seed   an integer or 1-D numpy array.
  alg   the RNG algorithm. Can be a string, an Algorithm or an integer.

 Returns   a 1-D numpy array whose size depends on the algorithm.


Module: tf.random.experimental Public API for tf.random.experimental namespace. Classes class Algorithm: An enumeration. class Generator: Random-number generator. Functions create_rng_state(...): Creates a RNG state from an integer or a vector. get_global_generator(...): Retrieves the global generator. set_global_generator(...): Replaces the global generator with another Generator object. stateless_fold_in(...): Folds in data to an RNG seed to form a new RNG seed. stateless_split(...): Splits an RNG seed into num new seeds by adding a leading axis.


tf.random.experimental.stateless_fold_in Folds in data to an RNG seed to form a new RNG seed.  View aliases  Compat aliases for migration
See Migration guide for more details. tf.compat.v1.random.experimental.stateless_fold_in
tf.random.experimental.stateless_fold_in(
    seed, data
)
 For example, in a distributed-training setting, suppose we have a master seed and a replica ID. We want to fold the replica ID into the master seed to form a "replica seed" to be used by that replica later on, so that different replicas will generate different random numbers but the reproducibility of the whole system can still be controlled by the master seed:
master_seed = [1, 2]
replica_id = 3
replica_seed = tf.random.experimental.stateless_fold_in(
  master_seed, replica_id)
print(replica_seed)
tf.Tensor([1105988140          3], shape=(2,), dtype=int32)
tf.random.stateless_normal(shape=[3], seed=replica_seed)
<tf.Tensor: shape=(3,), dtype=float32, numpy=array([0.03197195, 0.8979765 ,
0.13253039], dtype=float32)>

 Args
  seed   an RNG seed (a tensor with shape [2] and dtype int32 or int64). (When using XLA, only int32 is allowed.)
  data   an int32 or int64 scalar representing data to be folded in to the seed.

 Returns   A new RNG seed that is a deterministic function of the inputs and is statistically safe for producing a stream of new pseudo-random values. It will have the same dtype as data (if data doesn't have an explict dtype, the dtype will be determined by tf.convert_to_tensor).


tf.random.experimental.stateless_split Splits an RNG seed into num new seeds by adding a leading axis.  View aliases  Compat aliases for migration
See Migration guide for more details. tf.compat.v1.random.experimental.stateless_split
tf.random.experimental.stateless_split(
    seed, num=2
)
 Example:
seed = [1, 2]
new_seeds = tf.random.experimental.stateless_split(seed, num=3)
print(new_seeds)
tf.Tensor(
[[1105988140 1738052849]
 [-335576002  370444179]
 [  10670227 -246211131]], shape=(3, 2), dtype=int32)
tf.random.stateless_normal(shape=[3], seed=new_seeds[0, :])
<tf.Tensor: shape=(3,), dtype=float32, numpy=array([-0.59835213, -0.9578608 ,
0.9002807 ], dtype=float32)>

 Args
  seed   an RNG seed (a tensor with shape [2] and dtype int32 or int64). (When using XLA, only int32 is allowed.)
  num   optional, a positive integer or scalar tensor indicating the number of seeds to produce (default 2).

 Returns   A tensor with shape [num, 2] representing num new seeds. It will have the same dtype as seed (if seed doesn't have an explict dtype, the dtype will be determined by tf.convert_to_tensor).


tf.random.fixed_unigram_candidate_sampler     View source on GitHub    Samples a set of classes using the provided (fixed) base distribution.  View aliases  Main aliases
tf.nn.fixed_unigram_candidate_sampler Compat aliases for migration See Migration guide for more details. tf.compat.v1.nn.fixed_unigram_candidate_sampler, tf.compat.v1.random.fixed_unigram_candidate_sampler
tf.random.fixed_unigram_candidate_sampler(
    true_classes, num_true, num_sampled, unique, range_max, vocab_file='',
    distortion=1.0, num_reserved_ids=0, num_shards=1, shard=0, unigrams=(),
    seed=None, name=None
)
 This operation randomly samples a tensor of sampled classes (sampled_candidates) from the range of integers [0, range_max). The elements of sampled_candidates are drawn without replacement (if unique=True) or with replacement (if unique=False) from the base distribution. The base distribution is read from a file or passed in as an in-memory array. There is also an option to skew the distribution by applying a distortion power to the weights. In addition, this operation returns tensors true_expected_count and sampled_expected_count representing the number of times each of the target classes (true_classes) and the sampled classes (sampled_candidates) is expected to occur in an average tensor of sampled classes. These values correspond to Q(y|x) defined in this document. If unique=True, then these are post-rejection probabilities and we compute them approximately.

 Args
  true_classes   A Tensor of type int64 and shape [batch_size, num_true]. The target classes.
  num_true   An int. The number of target classes per training example.
  num_sampled   An int. The number of classes to randomly sample.
  unique   A bool. Determines whether all sampled classes in a batch are unique.
  range_max   An int. The number of possible classes.
  vocab_file   Each valid line in this file (which should have a CSV-like format) corresponds to a valid word ID. IDs are in sequential order, starting from num_reserved_ids. The last entry in each line is expected to be a value corresponding to the count or relative probability. Exactly one of vocab_file and unigrams needs to be passed to this operation.
  distortion   The distortion is used to skew the unigram probability distribution. Each weight is first raised to the distortion's power before adding to the internal unigram distribution. As a result, distortion = 1.0 gives regular unigram sampling (as defined by the vocab file), and distortion = 0.0 gives a uniform distribution.
  num_reserved_ids   Optionally some reserved IDs can be added in the range [0, num_reserved_ids) by the users. One use case is that a special unknown word token is used as ID 0. These IDs will have a sampling probability of 0.
  num_shards   A sampler can be used to sample from a subset of the original range in order to speed up the whole computation through parallelism. This parameter (together with shard) indicates the number of partitions that are being used in the overall computation.
  shard   A sampler can be used to sample from a subset of the original range in order to speed up the whole computation through parallelism. This parameter (together with num_shards) indicates the particular partition number of the operation, when partitioning is being used.
  unigrams   A list of unigram counts or probabilities, one per ID in sequential order. Exactly one of vocab_file and unigrams should be passed to this operation.
  seed   An int. An operation-specific seed. Default is 0.
  name   A name for the operation (optional).

 Returns
  sampled_candidates   A tensor of type int64 and shape [num_sampled]. The sampled classes.
  true_expected_count   A tensor of type float. Same shape as true_classes. The expected counts under the sampling distribution of each of true_classes.
  sampled_expected_count   A tensor of type float. Same shape as sampled_candidates. The expected counts under the sampling distribution of each of sampled_candidates.


tf.random.gamma     View source on GitHub    Draws shape samples from each of the given Gamma distribution(s).  View aliases  Compat aliases for migration
See Migration guide for more details. tf.compat.v1.random.gamma, tf.compat.v1.random_gamma
tf.random.gamma(
    shape, alpha, beta=None, dtype=tf.dtypes.float32, seed=None, name=None
)
 alpha is the shape parameter describing the distribution(s), and beta is the inverse scale parameter(s).
Note: Because internal calculations are done using float64 and casting has floor semantics, we must manually map zero outcomes to the smallest possible positive floating-point value, i.e., np.finfo(dtype).tiny. This means that np.finfo(dtype).tiny occurs more frequently than it otherwise should. This bias can only happen for small values of alpha, i.e., alpha << 1 or large values of beta, i.e., beta >> 1.
 The samples are differentiable w.r.t. alpha and beta. The derivatives are computed using the approach described in (Figurnov et al., 2018). Example: samples = tf.random.gamma([10], [0.5, 1.5])
# samples has shape [10, 2], where each slice [:, 0] and [:, 1] represents
# the samples drawn from each distribution

samples = tf.random.gamma([7, 5], [0.5, 1.5])
# samples has shape [7, 5, 2], where each slice [:, :, 0] and [:, :, 1]
# represents the 7x5 samples drawn from each of the two distributions

alpha = tf.constant([[1.],[3.],[5.]])
beta = tf.constant([[3., 4.]])
samples = tf.random.gamma([30], alpha=alpha, beta=beta)
# samples has shape [30, 3, 2], with 30 samples each of 3x2 distributions.

loss = tf.reduce_mean(tf.square(samples))
dloss_dalpha, dloss_dbeta = tf.gradients(loss, [alpha, beta])
# unbiased stochastic derivatives of the loss function
alpha.shape == dloss_dalpha.shape  # True
beta.shape == dloss_dbeta.shape  # True

 Args
  shape   A 1-D integer Tensor or Python array. The shape of the output samples to be drawn per alpha/beta-parameterized distribution.
  alpha   A Tensor or Python value or N-D array of type dtype. alpha provides the shape parameter(s) describing the gamma distribution(s) to sample. Must be broadcastable with beta.
  beta   A Tensor or Python value or N-D array of type dtype. Defaults to 1. beta provides the inverse scale parameter(s) of the gamma distribution(s) to sample. Must be broadcastable with alpha.
  dtype   The type of alpha, beta, and the output: float16, float32, or float64.
  seed   A Python integer. Used to create a random seed for the distributions. See tf.random.set_seed for behavior.
  name   Optional name for the operation.

 Returns
  samples   a Tensor of shape tf.concat([shape, tf.shape(alpha + beta)], axis=0) with values of type dtype.    References: Implicit Reparameterization Gradients: Figurnov et al., 2018 (pdf)


tf.random.Generator Random-number generator.  View aliases  Main aliases
tf.random.experimental.Generator Compat aliases for migration See Migration guide for more details. tf.compat.v1.random.Generator, tf.compat.v1.random.experimental.Generator
tf.random.Generator(
    copy_from=None, state=None, alg=None
)
 Example: Creating a generator from a seed:
g = tf.random.Generator.from_seed(1234)
g.normal(shape=(2, 3))
<tf.Tensor: shape=(2, 3), dtype=float32, numpy=
array([[ 0.9356609 ,  1.0854305 , -0.93788373],
       [-0.5061547 ,  1.3169702 ,  0.7137579 ]], dtype=float32)>
 Creating a generator from a non-deterministic state:
g = tf.random.Generator.from_non_deterministic_state()
g.normal(shape=(2, 3))
<tf.Tensor: shape=(2, 3), dtype=float32, numpy=...>
 All the constructors allow explicitly choosing an Random-Number-Generation (RNG) algorithm. Supported algorithms are "philox" and "threefry". For example:
g = tf.random.Generator.from_seed(123, alg="philox")
g.normal(shape=(2, 3))
<tf.Tensor: shape=(2, 3), dtype=float32, numpy=
array([[ 0.8673864 , -0.29899067, -0.9310337 ],
       [-1.5828488 ,  1.2481191 , -0.6770643 ]], dtype=float32)>
 CPU, GPU and TPU with the same algorithm and seed will generate the same integer random numbers. Float-point results (such as the output of normal) may have small numerical discrepancies between different devices. This class uses a tf.Variable to manage its internal state. Every time random numbers are generated, the state of the generator will change. For example:
g = tf.random.Generator.from_seed(1234)
g.state
<tf.Variable ... numpy=array([1234,    0,    0])>
g.normal(shape=(2, 3))
<...>
g.state
<tf.Variable ... numpy=array([2770,    0,    0])>
 The shape of the state is algorithm-specific. There is also a global generator:
g = tf.random.get_global_generator()
g.normal(shape=(2, 3))
<tf.Tensor: shape=(2, 3), dtype=float32, numpy=...>

 Args
  copy_from   a generator to be copied from.
  state   a vector of dtype STATE_TYPE representing the initial state of the RNG, whose length and semantics are algorithm-specific. If it's a variable, the generator will reuse it instead of creating a new variable.
  alg   the RNG algorithm. Possible values are tf.random.Algorithm.PHILOX for the Philox algorithm and tf.random.Algorithm.THREEFRY for the ThreeFry algorithm (see paper 'Parallel Random Numbers: As Easy as 1, 2, 3' [https://www.thesalmons.org/john/random123/papers/random123sc11.pdf]). The string names "philox" and "threefry" can also be used. Note PHILOX guarantees the same numbers are produced (given the same random state) across all architectures (CPU, GPU, XLA etc).

 Attributes
  algorithm   The RNG algorithm id (a Python integer or scalar integer Tensor).
  key   The 'key' part of the state of a counter-based RNG. For a counter-base RNG algorithm such as Philox and ThreeFry (as described in paper 'Parallel Random Numbers: As Easy as 1, 2, 3' [https://www.thesalmons.org/john/random123/papers/random123sc11.pdf]), the RNG state consists of two parts: counter and key. The output is generated via the formula: output=hash(key, counter), i.e. a hashing of the counter parametrized by the key. Two RNGs with two different keys can be thought as generating two independent random-number streams (a stream is formed by increasing the counter).

  state   The internal state of the RNG.    Methods binomial View source
binomial(
    shape, counts, probs, dtype=tf.dtypes.int32, name=None
)
 Outputs random values from a binomial distribution. The generated values follow a binomial distribution with specified count and probability of success parameters. Example: counts = [10., 20.]
# Probability of success.
probs = [0.8]

rng = tf.random.Generator.from_seed(seed=234)
binomial_samples = rng.binomial(shape=[2], counts=counts, probs=probs)

counts = ... # Shape [3, 1, 2]
probs = ...  # Shape [1, 4, 2]
shape = [3, 4, 3, 4, 2]
rng = tf.random.Generator.from_seed(seed=1717)
# Sample shape will be [3, 4, 3, 4, 2]
binomial_samples = rng.binomial(shape=shape, counts=counts, probs=probs)

 Args
  shape   A 1-D integer Tensor or Python array. The shape of the output tensor.
  counts   Tensor. The counts of the binomial distribution. Must be broadcastable with probs, and broadcastable with the rightmost dimensions of shape.
  probs   Tensor. The probability of success for the binomial distribution. Must be broadcastable with counts and broadcastable with the rightmost dimensions of shape.
  dtype   The type of the output. Default: tf.int32
  name   A name for the operation (optional).

 Returns
  samples   A Tensor of the specified shape filled with random binomial values. For each i, each samples[i, ...] is an independent draw from the binomial distribution on counts[i] trials with probability of success probs[i].    from_key_counter View source
@classmethod
from_key_counter(
    key, counter, alg
)
 Creates a generator from a key and a counter. This constructor only applies if the algorithm is a counter-based algorithm. See method key for the meaning of "key" and "counter".

 Args
  key   the key for the RNG, a scalar of type STATE_TYPE.
  counter   a vector of dtype STATE_TYPE representing the initial counter for the RNG, whose length is algorithm-specific.,
  alg   the RNG algorithm. If None, it will be auto-selected. See __init__ for its possible values.

 Returns   The new generator.
 Throws:
ValueError: if the generator is created inside a synchronous tf.distribute strategy such as MirroredStrategy or TPUStrategy, because there is ambiguity on how to replicate a generator (e.g. should it be copied so such each replica will get the same random numbers, or should it be "split" into different generators that generate different random numbers).  from_non_deterministic_state View source
@classmethod
from_non_deterministic_state(
    alg=None
)
 Creates a generator by non-deterministically initializing its state. The source of the non-determinism will be platform- and time-dependent.

 Args
  alg   (optional) the RNG algorithm. If None, it will be auto-selected. See __init__ for its possible values.

 Returns   The new generator.
 Throws:
ValueError: if the generator is created inside a synchronous tf.distribute strategy such as MirroredStrategy or TPUStrategy, because there is ambiguity on how to replicate a generator (e.g. should it be copied so such each replica will get the same random numbers, or should it be "split" into different generators that generate different random numbers).  from_seed View source
@classmethod
from_seed(
    seed, alg=None
)
 Creates a generator from a seed. A seed is a 1024-bit unsigned integer represented either as a Python integer or a vector of integers. Seeds shorter than 1024-bit will be padded. The padding, the internal structure of a seed and the way a seed is converted to a state are all opaque (unspecified). The only semantics specification of seeds is that two different seeds are likely to produce two independent generators (but no guarantee).

 Args
  seed   the seed for the RNG.
  alg   (optional) the RNG algorithm. If None, it will be auto-selected. See __init__ for its possible values.

 Returns   The new generator.
 Throws:
ValueError: if the generator is created inside a synchronous tf.distribute strategy such as MirroredStrategy or TPUStrategy, because there is ambiguity on how to replicate a generator (e.g. should it be copied so such each replica will get the same random numbers, or should it be "split" into different generators that generate different random numbers).  from_state View source
@classmethod
from_state(
    state, alg
)
 Creates a generator from a state. See __init__ for description of state and alg.

 Args
  state   the new state.
  alg   the RNG algorithm.

 Returns   The new generator.
 Throws:
ValueError: if the generator is created inside a synchronous tf.distribute strategy such as MirroredStrategy or TPUStrategy, because there is ambiguity on how to replicate a generator (e.g. should it be copied so such each replica will get the same random numbers, or should it be "split" into different generators that generate different random numbers).  make_seeds View source
make_seeds(
    count=1
)
 Generates seeds for stateless random ops. For example: seeds = get_global_generator().make_seeds(count=10)
for i in range(10):
  seed = seeds[:, i]
  numbers = stateless_random_normal(shape=[2, 3], seed=seed)
  ...

 Args
  count   the number of seed pairs (note that stateless random ops need a pair of seeds to invoke).

 Returns   A tensor of shape [2, count] and dtype int64.
 normal View source
normal(
    shape, mean=0.0, stddev=1.0, dtype=tf.dtypes.float32, name=None
)
 Outputs random values from a normal distribution.

 Args
  shape   A 1-D integer Tensor or Python array. The shape of the output tensor.
  mean   A 0-D Tensor or Python value of type dtype. The mean of the normal distribution.
  stddev   A 0-D Tensor or Python value of type dtype. The standard deviation of the normal distribution.
  dtype   The type of the output.
  name   A name for the operation (optional).

 Returns   A tensor of the specified shape filled with random normal values.
 reset View source
reset(
    state
)
 Resets the generator by a new state. See __init__ for the meaning of "state".

 Args
  state   the new state.    reset_from_key_counter View source
reset_from_key_counter(
    key, counter
)
 Resets the generator by a new key-counter pair. See from_key_counter for the meaning of "key" and "counter".

 Args
  key   the new key.
  counter   the new counter.    reset_from_seed View source
reset_from_seed(
    seed
)
 Resets the generator by a new seed. See from_seed for the meaning of "seed".

 Args
  seed   the new seed.    skip View source
skip(
    delta
)
 Advance the counter of a counter-based RNG.

 Args
  delta   the amount of advancement. The state of the RNG after skip(n) will be the same as that after normal([n]) (or any other distribution). The actual increment added to the counter is an unspecified implementation detail.    split View source
split(
    count=1
)
 Returns a list of independent Generator objects. Two generators are independent of each other in the sense that the random-number streams they generate don't have statistically detectable correlations. The new generators are also independent of the old one. The old generator's state will be changed (like other random-number generating methods), so two calls of split will return different new generators. For example: gens = get_global_generator().split(count=10)
for gen in gens:
  numbers = gen.normal(shape=[2, 3])
  # ...
gens2 = get_global_generator().split(count=10)
# gens2 will be different from gens
 The new generators will be put on the current device (possible different from the old generator's), for example: with tf.device("/device:CPU:0"):
  gen = Generator(seed=1234)  # gen is on CPU
with tf.device("/device:GPU:0"):
  gens = gen.split(count=10)  # gens are on GPU

 Args
  count   the number of generators to return.

 Returns   A list (length count) of Generator objects independent of each other. The new generators have the same RNG algorithm as the old one.
 truncated_normal View source
truncated_normal(
    shape, mean=0.0, stddev=1.0, dtype=tf.dtypes.float32, name=None
)
 Outputs random values from a truncated normal distribution. The generated values follow a normal distribution with specified mean and standard deviation, except that values whose magnitude is more than 2 standard deviations from the mean are dropped and re-picked.

 Args
  shape   A 1-D integer Tensor or Python array. The shape of the output tensor.
  mean   A 0-D Tensor or Python value of type dtype. The mean of the truncated normal distribution.
  stddev   A 0-D Tensor or Python value of type dtype. The standard deviation of the normal distribution, before truncation.
  dtype   The type of the output.
  name   A name for the operation (optional).

 Returns   A tensor of the specified shape filled with random truncated normal values.
 uniform View source
uniform(
    shape, minval=0, maxval=None, dtype=tf.dtypes.float32, name=None
)
 Outputs random values from a uniform distribution. The generated values follow a uniform distribution in the range [minval, maxval). The lower bound minval is included in the range, while the upper bound maxval is excluded. (For float numbers especially low-precision types like bfloat16, because of rounding, the result may sometimes include maxval.) For floats, the default range is [0, 1). For ints, at least maxval must be specified explicitly. In the integer case, the random integers are slightly biased unless maxval - minval is an exact power of two. The bias is small for values of maxval - minval significantly smaller than the range of the output (either 2**32 or 2**64). For full-range random integers, pass minval=None and maxval=None with an integer dtype (for integer dtypes, minval and maxval must be both None or both not None).

 Args
  shape   A 1-D integer Tensor or Python array. The shape of the output tensor.
  minval   A Tensor or Python value of type dtype, broadcastable with shape (for integer types, broadcasting is not supported, so it needs to be a scalar). The lower bound (included) on the range of random values to generate. Pass None for full-range integers. Defaults to 0.
  maxval   A Tensor or Python value of type dtype, broadcastable with shape (for integer types, broadcasting is not supported, so it needs to be a scalar). The upper bound (excluded) on the range of random values to generate. Pass None for full-range integers. Defaults to 1 if dtype is floating point.
  dtype   The type of the output.
  name   A name for the operation (optional).

 Returns   A tensor of the specified shape filled with random uniform values.

 Raises
  ValueError   If dtype is integral and maxval is not specified.    uniform_full_int View source
uniform_full_int(
    shape, dtype=tf.dtypes.uint64, name=None
)
 Uniform distribution on an integer type's entire range. This method is the same as setting minval and maxval to None in the uniform method.

 Args
  shape   the shape of the output.
  dtype   (optional) the integer type, default to uint64.
  name   (optional) the name of the node.

 Returns   A tensor of random numbers of the required shape.


tf.random.get_global_generator Retrieves the global generator.  View aliases  Main aliases
tf.random.experimental.get_global_generator Compat aliases for migration See Migration guide for more details. tf.compat.v1.random.experimental.get_global_generator, tf.compat.v1.random.get_global_generator
tf.random.get_global_generator()
 This function will create the global generator the first time it is called, and the generator will be placed at the default device at that time, so one needs to be careful when this function is first called. Using a generator placed on a less-ideal device will incur performance regression.

 Returns   The global tf.random.Generator object.


tf.random.learned_unigram_candidate_sampler     View source on GitHub    Samples a set of classes from a distribution learned during training.  View aliases  Main aliases
tf.nn.learned_unigram_candidate_sampler Compat aliases for migration See Migration guide for more details. tf.compat.v1.nn.learned_unigram_candidate_sampler, tf.compat.v1.random.learned_unigram_candidate_sampler
tf.random.learned_unigram_candidate_sampler(
    true_classes, num_true, num_sampled, unique, range_max, seed=None, name=None
)
 This operation randomly samples a tensor of sampled classes (sampled_candidates) from the range of integers [0, range_max). The elements of sampled_candidates are drawn without replacement (if unique=True) or with replacement (if unique=False) from the base distribution. The base distribution for this operation is constructed on the fly during training. It is a unigram distribution over the target classes seen so far during training. Every integer in [0, range_max) begins with a weight of 1, and is incremented by 1 each time it is seen as a target class. The base distribution is not saved to checkpoints, so it is reset when the model is reloaded. In addition, this operation returns tensors true_expected_count and sampled_expected_count representing the number of times each of the target classes (true_classes) and the sampled classes (sampled_candidates) is expected to occur in an average tensor of sampled classes. These values correspond to Q(y|x) defined in this document. If unique=True, then these are post-rejection probabilities and we compute them approximately.

 Args
  true_classes   A Tensor of type int64 and shape [batch_size, num_true]. The target classes.
  num_true   An int. The number of target classes per training example.
  num_sampled   An int. The number of classes to randomly sample.
  unique   A bool. Determines whether all sampled classes in a batch are unique.
  range_max   An int. The number of possible classes.
  seed   An int. An operation-specific seed. Default is 0.
  name   A name for the operation (optional).

 Returns
  sampled_candidates   A tensor of type int64 and shape [num_sampled]. The sampled classes.
  true_expected_count   A tensor of type float. Same shape as true_classes. The expected counts under the sampling distribution of each of true_classes.
  sampled_expected_count   A tensor of type float. Same shape as sampled_candidates. The expected counts under the sampling distribution of each of sampled_candidates.