Manipulation

tf.sparse_concat(concat_dim, sp_inputs, name=None, expand_nonconcat_dim=False)

Concatenates a list of SparseTensor along the specified dimension.

Concatenation is with respect to the dense versions of each sparse input. It is assumed that each inputs is a SparseTensor whose elements are ordered along increasing dimension number.

If expand_nonconcat_dim is False, all inputs' shapes must match, except for the concat dimension. If expand_nonconcat_dim is True, then inputs' shapes are allowd to vary among all inputs.

The indices, values, and shapes lists must have the same length.

If expand_nonconcat_dim is False, then the output shape is identical to the inputs', except along the concat dimension, where it is the sum of the inputs' sizes along that dimension.

If expand_nonconcat_dim is True, then the output shape along the non-concat dimensions will be expand to be the largest among all inputs, and it is the sum of the inputs sizes along the concat dimension.

The output elements will be resorted to preserve the sort order along increasing dimension number.

This op runs in O(M log M) time, where M is the total number of non-empty values across all inputs. This is due to the need for an internal sort in order to concatenate efficiently across an arbitrary dimension.

For example, if concat_dim = 1 and the inputs are

sp_inputs[0]: shape = [2, 3]
[0, 2]: "a"
[1, 0]: "b"
[1, 1]: "c"

sp_inputs[1]: shape = [2, 4]
[0, 1]: "d"
[0, 2]: "e"

then the output will be

shape = [2, 7]
[0, 2]: "a"
[0, 4]: "d"
[0, 5]: "e"
[1, 0]: "b"
[1, 1]: "c"

Graphically this is equivalent to doing

[    a] concat [  d e  ] = [    a   d e  ]
[b c  ]        [       ]   [b c          ]

Another example, if 'concat_dim = 1' and the inputs are

sp_inputs[0]: shape = [3, 3]
[0, 2]: "a"
[1, 0]: "b"
[2, 1]: "c"

sp_inputs[1]: shape = [2, 4]
[0, 1]: "d"
[0, 2]: "e"

if expand_nonconcat_dim = False, this will result in an error. But if expand_nonconcat_dim = True, this will result in:

shape = [3, 7]
[0, 2]: "a"
[0, 4]: "d"
[0, 5]: "e"
[1, 0]: "b"
[2, 1]: "c"

Graphically this is equivalent to doing

[    a] concat [  d e  ] = [    a   d e  ]
[b    ]        [       ]   [b            ]
[  c  ]                    [  c          ]
Args:
  • concat_dim: Dimension to concatenate along. Must be in range [-rank, rank), where rank is the number of dimensions in each input SparseTensor.
  • sp_inputs: List of SparseTensor to concatenate.
  • name: A name prefix for the returned tensors (optional).
  • expand_nonconcat_dim: Whether to allow the expansion in the non-concat dimensions. Defaulted to False.
Returns:

A SparseTensor with the concatenated output.

Raises:
  • TypeError: If sp_inputs is not a list of SparseTensor.

tf.sparse_reorder(sp_input, name=None)

Reorders a SparseTensor into the canonical, row-major ordering.

Note that by convention, all sparse ops preserve the canonical ordering along increasing dimension number. The only time ordering can be violated is during manual manipulation of the indices and values to add entries.

Reordering does not affect the shape of the SparseTensor.

For example, if sp_input has shape [4, 5] and indices / values:

[0, 3]: b
[0, 1]: a
[3, 1]: d
[2, 0]: c

then the output will be a SparseTensor of shape [4, 5] and indices / values:

[0, 1]: a
[0, 3]: b
[2, 0]: c
[3, 1]: d
Args:
  • sp_input: The input SparseTensor.
  • name: A name prefix for the returned tensors (optional)
Returns:

A SparseTensor with the same shape and non-empty values, but in canonical ordering.

Raises:
  • TypeError: If sp_input is not a SparseTensor.

tf.sparse_reshape(sp_input, shape, name=None)

Reshapes a SparseTensor to represent values in a new dense shape.

This operation has the same semantics as reshape on the represented dense tensor. The indices of non-empty values in sp_input are recomputed based on the new dense shape, and a new SparseTensor is returned containing the new indices and new shape. The order of non-empty values in sp_input is unchanged.

If one component of shape is the special value -1, the size of that dimension is computed so that the total dense size remains constant. At most one component of shape can be -1. The number of dense elements implied by shape must be the same as the number of dense elements originally represented by sp_input.

For example, if sp_input has shape [2, 3, 6] and indices / values:

[0, 0, 0]: a
[0, 0, 1]: b
[0, 1, 0]: c
[1, 0, 0]: d
[1, 2, 3]: e

and shape is [9, -1], then the output will be a SparseTensor of shape [9, 4] and indices / values:

[0, 0]: a
[0, 1]: b
[1, 2]: c
[4, 2]: d
[8, 1]: e
Args:
  • sp_input: The input SparseTensor.
  • shape: A 1-D (vector) int64 Tensor specifying the new dense shape of the represented SparseTensor.
  • name: A name prefix for the returned tensors (optional)
Returns:

A SparseTensor with the same non-empty values but with indices calculated by the new dense shape.

Raises:
  • TypeError: If sp_input is not a SparseTensor.

tf.sparse_split(split_dim, num_split, sp_input, name=None)

Split a SparseTensor into num_split tensors along split_dim.

If the sp_input.shape[split_dim] is not an integer multiple of num_split each slice starting from 0:shape[split_dim] % num_split gets extra one dimension. For example, if split_dim = 1 and num_split = 2 and the input is:

input_tensor = shape = [2, 7]
[    a   d e  ]
[b c          ]

Graphically the output tensors are:

output_tensor[0] =
[    a ]
[b c   ]

output_tensor[1] =
[ d e  ]
[      ]
Args:
  • split_dim: A 0-D int32 Tensor. The dimension along which to split.
  • num_split: A Python integer. The number of ways to split.
  • sp_input: The SparseTensor to split.
  • name: A name for the operation (optional).
Returns:

num_split SparseTensor objects resulting from splitting value.

Raises:
  • TypeError: If sp_input is not a SparseTensor.

tf.sparse_retain(sp_input, to_retain)

Retains specified non-empty values within a SparseTensor.

For example, if sp_input has shape [4, 5] and 4 non-empty string values:

[0, 1]: a
[0, 3]: b
[2, 0]: c
[3, 1]: d

and to_retain = [True, False, False, True], then the output will be a SparseTensor of shape [4, 5] with 2 non-empty values:

[0, 1]: a
[3, 1]: d
Args:
  • sp_input: The input SparseTensor with N non-empty elements.
  • to_retain: A bool vector of length N with M true values.
Returns:

A SparseTensor with the same shape as the input and M non-empty elements corresponding to the true positions in to_retain.

Raises:
  • TypeError: If sp_input is not a SparseTensor.

tf.sparse_reset_shape(sp_input, new_shape=None)

Resets the shape of a SparseTensor with indices and values unchanged.

If new_shape is None, returns a copy of sp_input with its shape reset to the tight bounding box of sp_input.

If new_shape is provided, then it must be larger or equal in all dimensions compared to the shape of sp_input. When this condition is met, the returned SparseTensor will have its shape reset to new_shape and its indices and values unchanged from that of sp_input.

For example:

Consider a sp_input with shape [2, 3, 5]:

[0, 0, 1]: a
[0, 1, 0]: b
[0, 2, 2]: c
[1, 0, 3]: d
  • It is an error to set new_shape as [3, 7] since this represents a rank-2 tensor while sp_input is rank-3. This is either a ValueError during graph construction (if both shapes are known) or an OpError during run time.

  • Setting new_shape as [2, 3, 6] will be fine as this shape is larger or equal in every dimension compared to the original shape [2, 3, 5].

  • On the other hand, setting new_shape as [2, 3, 4] is also an error: The third dimension is smaller than the original shape [2, 3, 5] (and an InvalidArgumentError will be raised).

  • If new_shape is None, the returned SparseTensor will have a shape [2, 3, 4], which is the tight bounding box of sp_input.

Args:
  • sp_input: The input SparseTensor.
  • new_shape: None or a vector representing the new shape for the returned SparseTensor.
Returns:

A SparseTensor indices and values unchanged from input_sp. Its shape is new_shape if that is set. Otherwise it is the tight bounding box of input_sp

Raises:
  • TypeError: If sp_input is not a SparseTensor.
  • ValueError: If new_shape represents a tensor with a different rank from that of sp_input (if shapes are known when graph is constructed).
  • OpError:
    • If new_shape has dimension sizes that are too small.
    • If shapes are not known during graph construction time, and during run time it is found out that the ranks do not match.

tf.sparse_fill_empty_rows(sp_input, default_value, name=None)

Fills empty rows in the input 2-D SparseTensor with a default value.

This op adds entries with the specified default_value at index [row, 0] for any row in the input that does not already have a value.

For example, suppose sp_input has shape [5, 6] and non-empty values:

[0, 1]: a
[0, 3]: b
[2, 0]: c
[3, 1]: d

Rows 1 and 4 are empty, so the output will be of shape [5, 6] with values:

[0, 1]: a
[0, 3]: b
[1, 0]: default_value
[2, 0]: c
[3, 1]: d
[4, 0]: default_value

Note that the input may have empty columns at the end, with no effect on this op.

The output SparseTensor will be in row-major order and will have the same shape as the input.

This op also returns an indicator vector such that

empty_row_indicator[i] = True iff row i was an empty row.
Args:
  • sp_input: A SparseTensor with shape [N, M].
  • default_value: The value to fill for empty rows, with the same type as sp_input.
  • name: A name prefix for the returned tensors (optional)
Returns:
  • sp_ordered_output: A SparseTensor with shape [N, M], and with all empty rows filled in with default_value.
  • empty_row_indicator: A bool vector of length N indicating whether each input row was empty.
Raises:
  • TypeError: If sp_input is not a SparseTensor.

tf.sparse_transpose(sp_input, perm=None, name=None)

Transposes a SparseTensor

The returned tensor's dimension i will correspond to the input dimension perm[i]. If perm is not given, it is set to (n-1...0), where n is the rank of the input tensor. Hence by default, this operation performs a regular matrix transpose on 2-D input Tensors.

For example, if sp_input has shape [4, 5] and indices / values:

[0, 3]: b
[0, 1]: a
[3, 1]: d
[2, 0]: c

then the output will be a SparseTensor of shape [5, 4] and indices / values:

[0, 2]: c
[1, 0]: a
[1, 3]: d
[3, 0]: b
Args:
  • sp_input: The input SparseTensor.
  • perm: A permutation of the dimensions of sp_input.
  • name: A name prefix for the returned tensors (optional)
Returns:

A transposed SparseTensor.

Raises:
  • TypeError: If sp_input is not a SparseTensor.