Skip to content

_gather

gather

Gather specific indices from a tensor.

The indices will automatically be cast to the correct type (tf, torch, np) based on the type of the tensor.

This method can be used with Numpy data:

ind = np.array([1, 0, 1])
n = np.array([[0, 1], [2, 3], [4, 5]])
b = fe.backend.gather(n, ind)  # [[2, 3], [0, 1], [2, 3]]
n = np.array([[[0, 1], [2, 3]], [[4, 5], [6, 7]], [[8, 9], [10, 11]]])
b = fe.backend.gather(n, ind)  # [[[4, 5], [6, 7]], [[0, 1], [2, 3]], [[4, 5], [6, 7]]]

This method can be used with TensorFlow tensors:

ind = tf.constant([1, 0, 1])
t = tf.constant([[0, 1], [2, 3], [4, 5]])
b = fe.backend.gather(t, ind)  # [[2, 3], [0, 1], [2, 3]]
t = tf.constant([[[0, 1], [2, 3]], [[4, 5], [6, 7]], [[8, 9], [10, 11]]])
b = fe.backend.gather(t, ind)  # [[[4, 5], [6, 7]], [[0, 1], [2, 3]], [[4, 5], [6, 7]]]

This method can be used with PyTorch tensors:

ind = torch.tensor([1, 0, 1])
p = torch.tensor([[0, 1], [2, 3], [4, 5]])
b = fe.backend.gather(p, ind)  # [[2, 3], [0, 1], [2, 3]]
p = torch.tensor([[[0, 1], [2, 3]], [[4, 5], [6, 7]], [[8, 9], [10, 11]]])
b = fe.backend.gather(p, ind)  # [[[4, 5], [6, 7]], [[0, 1], [2, 3]], [[4, 5], [6, 7]]]

Parameters:

Name Type Description Default
tensor Tensor

A tensor to gather values from.

required
indices Tensor

A tensor indicating which indices should be selected. These represent locations along the 0 axis.

required

Returns:

Type Description
Tensor

A tensor containing the elements from tensor at the given indices.

Raises:

Type Description
ValueError

If tensor is an unacceptable data type.

Source code in fastestimator/fastestimator/backend/_gather.py
def gather(tensor: Tensor, indices: Tensor) -> Tensor:
    """Gather specific indices from a tensor.

    The `indices` will automatically be cast to the correct type (tf, torch, np) based on the type of the `tensor`.

    This method can be used with Numpy data:
    ```python
    ind = np.array([1, 0, 1])
    n = np.array([[0, 1], [2, 3], [4, 5]])
    b = fe.backend.gather(n, ind)  # [[2, 3], [0, 1], [2, 3]]
    n = np.array([[[0, 1], [2, 3]], [[4, 5], [6, 7]], [[8, 9], [10, 11]]])
    b = fe.backend.gather(n, ind)  # [[[4, 5], [6, 7]], [[0, 1], [2, 3]], [[4, 5], [6, 7]]]
    ```

    This method can be used with TensorFlow tensors:
    ```python
    ind = tf.constant([1, 0, 1])
    t = tf.constant([[0, 1], [2, 3], [4, 5]])
    b = fe.backend.gather(t, ind)  # [[2, 3], [0, 1], [2, 3]]
    t = tf.constant([[[0, 1], [2, 3]], [[4, 5], [6, 7]], [[8, 9], [10, 11]]])
    b = fe.backend.gather(t, ind)  # [[[4, 5], [6, 7]], [[0, 1], [2, 3]], [[4, 5], [6, 7]]]
    ```

    This method can be used with PyTorch tensors:
    ```python
    ind = torch.tensor([1, 0, 1])
    p = torch.tensor([[0, 1], [2, 3], [4, 5]])
    b = fe.backend.gather(p, ind)  # [[2, 3], [0, 1], [2, 3]]
    p = torch.tensor([[[0, 1], [2, 3]], [[4, 5], [6, 7]], [[8, 9], [10, 11]]])
    b = fe.backend.gather(p, ind)  # [[[4, 5], [6, 7]], [[0, 1], [2, 3]], [[4, 5], [6, 7]]]
    ```

    Args:
        tensor: A tensor to gather values from.
        indices: A tensor indicating which indices should be selected. These represent locations along the 0 axis.

    Returns:
        A tensor containing the elements from `tensor` at the given `indices`.

    Raises:
        ValueError: If `tensor` is an unacceptable data type.
    """
    if tf.is_tensor(tensor):
        indices = to_tensor(indices, 'tf')
        indices = tf.cast(indices, tf.int64)
        return tf.gather(tensor, indices=squeeze(indices), axis=0)
    elif isinstance(tensor, torch.Tensor):
        return tensor[squeeze(indices).type(torch.int64)]
    elif isinstance(tensor, np.ndarray):
        return np.take(tensor, squeeze(indices).astype('int64'), axis=0)
    else:
        raise ValueError("Unrecognized tensor type {}".format(type(tensor)))