Utility functions

redcat.utils.array

Contain utility functions for numpy.ndarrays.

redcat.utils.array.arrays_share_data

arrays_share_data(x: ndarray, y: ndarray) -> bool

Indicate if two arrays share the same data.

Parameters:

Name	Type	Description	Default
x	ndarray	Specifies the first array.	required
y	ndarray	Specifies the second array.	required

Returns:

Type	Description
bool	True if the two arrays share the same data, otherwise False.

Example usage:

>>> import numpy as np
>>> from redcat.utils.array import arrays_share_data
>>> x = np.ones((2, 3))
>>> arrays_share_data(x, x)
True
>>> arrays_share_data(x, x.copy())
False
>>> y = x[1:]
>>> arrays_share_data(x, y)
True

redcat.utils.array.get_data_base

get_data_base(array: ndarray) -> ndarray

Return the base array that owns the actual data.

Parameters:

Name	Type	Description	Default
array	ndarray	Specifies the input array.	required

Returns:

Type	Description
ndarray	The array that owns the actual data.

Example usage:

>>> import numpy as np
>>> from redcat.utils.array import get_data_base
>>> x = np.ones((2, 3))
>>> get_data_base(x)
array([[1., 1., 1.],
       [1., 1., 1.]])
>>> y = x[1:]
>>> get_data_base(y)
array([[1., 1., 1.],
       [1., 1., 1.]])

redcat.utils.array.get_div_rounding_operator

get_div_rounding_operator(mode: str | None) -> Callable

Get the rounding operator for a division.

Parameters:

Name	Type	Description	Default
mode	str | None	Specifies the type of rounding applied to the result. - None: true division. - "floor": floor division.	required

Returns:

Type	Description
Callable	The rounding operator for a division

Example usage:

>>> from redcat.utils.array import get_div_rounding_operator
>>> get_div_rounding_operator(None)
<ufunc 'divide'>

redcat.utils.array.permute_along_axis

permute_along_axis(
    array: ndarray, permutation: ndarray, axis: int = 0
) -> ndarray

Permutes the values of a array along a given axis.

Parameters:

Name	Type	Description	Default
array	ndarray	Specifies the array to permute.	required
permutation	ndarray	Specifies the permutation to use on the array. The dimension of this array should be compatible with the shape of the array to permute.	required
axis	int	Specifies the axis used to permute the array.	0

Returns:

Type	Description
ndarray	The permuted array.

Example usage:

>>> import numpy as np
>>> from redcat.utils.array import permute_along_axis
>>> permute_along_axis(np.arange(4), permutation=np.array([0, 2, 1, 3]))
array([0, 2, 1, 3])
>>> permute_along_axis(
...     np.arange(20).reshape(4, 5),
...     permutation=np.array([0, 2, 1, 3]),
... )
array([[ 0,  1,  2,  3,  4],
       [10, 11, 12, 13, 14],
       [ 5,  6,  7,  8,  9],
       [15, 16, 17, 18, 19]])
>>> permute_along_axis(
...     np.arange(20).reshape(4, 5),
...     permutation=np.array([0, 4, 2, 1, 3]),
...     axis=1,
... )
array([[ 0,  4,  2,  1,  3],
       [ 5,  9,  7,  6,  8],
       [10, 14, 12, 11, 13],
       [15, 19, 17, 16, 18]])
>>> permute_along_axis(
...     np.arange(20).reshape(2, 2, 5),
...     permutation=np.array([0, 4, 2, 1, 3]),
...     axis=2,
... )
array([[[ 0,  4,  2,  1,  3],
        [ 5,  9,  7,  6,  8]],
       [[10, 14, 12, 11, 13],
        [15, 19, 17, 16, 18]]])

redcat.utils.array.to_array

to_array(
    data: BaseBatch | Sequence | Tensor | ndarray,
) -> ndarray

Convert the input to a numpy.ndarray.

Parameters:

Name	Type	Description	Default
data	BaseBatch | Sequence | Tensor | ndarray	Specifies the data to convert to an array.	required

Returns:

Type	Description
ndarray	A NumPy array.

Example usage:

>>> from redcat.utils.array import to_array
>>> x = to_array([1, 2, 3, 4, 5])
>>> x
array([1, 2, 3, 4, 5])

redcat.utils.collection

Contain utility functions for collection objects.

redcat.utils.collection.to_list

to_list(
    data: list | tuple | Tensor | ndarray | BaseBatch,
) -> list

Convert an input data to a list.

Parameters:

Name	Type	Description	Default
data	list | tuple | Tensor | ndarray | BaseBatch	Specifies the data to convert.	required

Returns:

Type	Description
list	The data.

Example usage:

>>> from redcat import BatchList
>>> from redcat.utils.collection import to_list
>>> to_list(BatchList([1, 2, 3]))
[1, 2, 3]

redcat.utils.common

Contain utility functions.

redcat.utils.common.check_batch_dims

check_batch_dims(dims: set[int]) -> None

Get the batch dimensions from the inputs.

Parameters:

Name	Type	Description	Default
dims	set[int]	Specifies the batch dims to check.	required

Raises:

Type	Description
RuntimeError	if there are more than one batch dimension.

Example usage:

>>> from redcat.utils.common import check_batch_dims
>>> check_batch_dims({0})

redcat.utils.common.check_data_and_dim

check_data_and_dim(
    data: ndarray | Tensor, batch_dim: int
) -> None

Check if the array data and batch_dim are correct.

Parameters:

Name	Type	Description	Default
data	ndarray | Tensor	Specifies the array in the batch.	required
batch_dim	int	Specifies the batch dimension in the array object.	required

Raises:

Type	Description
RuntimeError	if one of the input is incorrect.

Example usage:

>>> import numpy as np
>>> import torch
>>> from redcat.utils.common import check_data_and_dim
>>> check_data_and_dim(np.ones((2, 3)), batch_dim=0)
>>> check_data_and_dim(torch.ones(2, 3), batch_dim=0)

redcat.utils.common.check_seq_dims

check_seq_dims(dims: set[int]) -> None

Get the sequence dimensions from the inputs.

Parameters:

Name	Type	Description	Default
dims	set[int]	Specifies the sequence dims to check.	required

Raises:

Type	Description
RuntimeError	if there are more than one sequence dimension.

Example usage:

>>> from redcat.utils.common import check_seq_dims
>>> check_seq_dims({1})

redcat.utils.common.get_batch_dims

get_batch_dims(
    args: Iterable[Any],
    kwargs: Mapping[str, Any] | None = None,
) -> set[int]

Get the batch dimensions from the inputs.

Parameters:

Name	Type	Description	Default
args	Iterable[Any]	Variable length argument list.	required
kwargs	Mapping[str, Any] | None	Arbitrary keyword arguments.	None

Returns:

Type	Description
set[int]	The batch dimensions.

Example usage:

>>> import numpy as np
>>> import torch
>>> from redcat import BatchedTensor
>>> from redcat.utils.common import get_batch_dims
>>> get_batch_dims(
...     args=(BatchedTensor(torch.ones(2, 3)), BatchedTensor(torch.ones(2, 6))),
...     kwargs={"batch": BatchedTensor(torch.ones(2, 4))},
... )
{0}

redcat.utils.common.get_data

get_data(data: BaseBatch[T] | Any) -> T

Get the data from a batch or the input data.

Parameters:

Name	Type	Description	Default
data	BaseBatch[T] | Any	Specifies the data.	required

Returns:

Type	Description
T	The data.

Example usage:

>>> import numpy as np
>>> import torch
>>> from redcat import BatchedTensor
>>> from redcat.ba import BatchedArray
>>> from redcat.utils.common import get_data
>>> get_data(BatchedArray(np.ones((2, 3))))
array([[1., 1., 1.],
       [1., 1., 1.]])
>>> get_data(BatchedTensor(torch.ones(2, 3)))
tensor([[1., 1., 1.],
        [1., 1., 1.]])
>>> get_data(torch.ones(2, 3))
tensor([[1., 1., 1.],
        [1., 1., 1.]])

redcat.utils.common.get_seq_dims

get_seq_dims(
    args: Iterable[Any, ...],
    kwargs: Mapping[str, Any] | None = None,
) -> set[int]

Get the sequence dimensions from the inputs.

Parameters:

Name	Type	Description	Default
args	Iterable[Any, ...]	Variable length argument list.	required
kwargs	Mapping[str, Any] | None	Arbitrary keyword arguments.	None

Returns:

Type	Description
set[int]	The sequence dimensions.

Example usage:

>>> import torch
>>> from redcat import BatchedTensorSeq
>>> from redcat.utils.common import get_seq_dims
>>> get_seq_dims(
...     args=(BatchedTensorSeq(torch.ones(2, 3)), BatchedTensorSeq(torch.ones(2, 6))),
...     kwargs={"batch": BatchedTensorSeq(torch.ones(2, 4))},
... )
{1}

redcat.utils.common.swap2

swap2(sequence: Tensor, index0: int, index1: int) -> Tensor

swap2(
    sequence: ndarray, index0: int, index1: int
) -> ndarray

swap2(
    sequence: MutableSequence, index0: int, index1: int
) -> MutableSequence

swap2(
    sequence: Tensor | ndarray | MutableSequence,
    index0: int,
    index1: int,
) -> Tensor | ndarray | MutableSequence

Swap two values in a mutable sequence.

The swap is performed in-place.

Parameters:

Name	Type	Description	Default
sequence	Tensor | ndarray | MutableSequence	Specifies the sequence to update.	required
index0	int	Specifies the index of the first value to swap.	required
index1	int	Specifies the index of the second value to swap.	required

Returns:

Type	Description
Tensor | ndarray | MutableSequence	The updated sequence.

Example usage:

>>> from redcat.utils.common import swap2
>>> seq = [1, 2, 3, 4, 5]
>>> swap2(seq, 2, 0)
>>> seq
[3, 2, 1, 4, 5]

redcat.utils.random

Contain utility functions to manage randomness.

redcat.utils.random.get_random_rng

get_random_rng(
    rng_or_seed: Random | int | None = None,
) -> Random

Get a random number generator.

Parameters:

Name	Type	Description	Default
rng_or_seed	Random | int | None	Specifies the pseudorandom number generator for sampling or the random seed for the random number generator.	None

Returns:

Type	Description
Random	The initialized random number generator.

Example usage:

>>> from redcat.utils.random import get_random_rng
>>> get_random_rng(42)
<random.Random object at 0x...>

redcat.utils.random.randperm

randperm(n: int, rng: Generator) -> ndarray

randperm(n: int, rng: Generator) -> Tensor

randperm(
    n: int, generator: Random | int | None = None
) -> list[int]

randperm(
    n: int, rng_or_seed: RNGType | int | None = None
) -> Tensor | ndarray | list[int]

Create a random permutation of integers from 0 to n - 1.

Parameters:

Name	Type	Description	Default
n	int	Specifies the number of items.	required
rng_or_seed	RNGType | int | None	Specifies the pseudorandom number generator for sampling or the random seed for the random number generator.	None

Returns:

Type	Description
Tensor | ndarray | list[int]	A random permutation of integers from 0 to n - 1.

Example usage:

>>> import numpy as np
>>> from redcat.utils.random import randperm
>>> randperm(10, np.random.default_rng(42))
array([...])

>>> from redcat.utils.tensor import get_torch_generator
>>> from redcat.utils.random import randperm
>>> randperm(10, get_torch_generator(42))
tensor([...])

>>> from redcat.utils.random import randperm
>>> randperm(10, 42)
[...]

redcat.utils.tensor

Contain utility functions for torch.Tensors.

redcat.utils.tensor.align_to_batch_first

align_to_batch_first(
    tensor: Tensor, batch_dim: int
) -> Tensor

Aligns the input tensor format to (batch_size, *) where * means any number of dimensions.

Parameters:

Name	Type	Description	Default
tensor	Tensor	Specifies the tensor to change format.	required
batch_dim	int	Specifies the batch dimension in the input tensor.	required

Returns:

Type	Description
Tensor	A tensor of shape (batch_size, *) where * means any number of dimensions.

Example usage:

>>> import torch
>>> from redcat.utils.tensor import align_to_batch_first
>>> align_to_batch_first(torch.arange(20).view(4, 5), batch_dim=1)
tensor([[ 0,  5, 10, 15],
        [ 1,  6, 11, 16],
        [ 2,  7, 12, 17],
        [ 3,  8, 13, 18],
        [ 4,  9, 14, 19]])

redcat.utils.tensor.align_to_batch_seq

align_to_batch_seq(
    tensor: Tensor, batch_dim: int, seq_dim: int
) -> Tensor

Aligns the input tensor format to (batch_size, sequence_length, *) where * means any number of dimensions.

Parameters:

Name	Type	Description	Default
tensor	Tensor	Specifies the tensor to change format.	required
batch_dim	int	Specifies the batch dimension in the input tensor.	required
seq_dim	int	Specifies the sequence dimension in the input tensor.	required

Returns:

Type	Description
Tensor	A tensor of shape (batch_size, sequence_length, *) where * means any number of dimensions.

Example usage:

>>> import torch
>>> from redcat.utils.tensor import align_to_batch_seq
>>> align_to_batch_seq(torch.arange(20).view(4, 5), batch_dim=1, seq_dim=0)
tensor([[ 0,  5, 10, 15],
        [ 1,  6, 11, 16],
        [ 2,  7, 12, 17],
        [ 3,  8, 13, 18],
        [ 4,  9, 14, 19]])

redcat.utils.tensor.align_to_seq_batch

align_to_seq_batch(
    tensor: Tensor, batch_dim: int, seq_dim: int
) -> Tensor

Aligns the input tensor format to (sequence_length, batch_size, *) where * means any number of dimensions.

Parameters:

Name	Type	Description	Default
tensor	Tensor	Specifies the tensor to change format.	required
batch_dim	int	Specifies the batch dimension in the input tensor.	required
seq_dim	int	Specifies the sequence dimension in the input tensor.	required

Returns:

Type	Description
Tensor	A tensor of shape (sequence_length, batch_size, *) where * means any number of dimensions.

Example usage:

>>> import torch
>>> from redcat.utils.tensor import align_to_seq_batch
>>> align_to_seq_batch(torch.arange(20).view(4, 5), batch_dim=0, seq_dim=1)
tensor([[ 0,  5, 10, 15],
        [ 1,  6, 11, 16],
        [ 2,  7, 12, 17],
        [ 3,  8, 13, 18],
        [ 4,  9, 14, 19]])

redcat.utils.tensor.compute_batch_seq_permutation

compute_batch_seq_permutation(
    num_dims: int,
    old_batch_dim: int,
    old_seq_dim: int,
    new_batch_dim: int,
    new_seq_dim: int,
) -> list[int]

Compute the permutation to update the batch and sequence dimensions.

Parameters:

Name	Type	Description	Default
num_dims	int	Specifies the number of dimensions.	required
old_batch_dim	int	Specifies the old batch dimension.	required
old_seq_dim	int	Specifies the old sequence dimension.	required
new_batch_dim	int	Specifies the new batch dimension.	required
new_seq_dim	int	Specifies the new sequence dimension.	required

Returns:

Type	Description
list[int]	The permutation to update the batch and sequence dimensions.

Example usage:

>>> from redcat.utils.tensor import compute_batch_seq_permutation
>>> compute_batch_seq_permutation(5, 0, 1, 1, 0)
[1, 0, 2, 3, 4]
>>> compute_batch_seq_permutation(2, 0, 1, 1, 0)
[1, 0]
>>> compute_batch_seq_permutation(5, 0, 1, 2, 0)
[1, 2, 0, 3, 4]
>>> compute_batch_seq_permutation(5, 0, 1, 1, 2)
[2, 0, 1, 3, 4]

redcat.utils.tensor.get_torch_generator

get_torch_generator(
    random_seed: int = 1,
    device: device | str | None = "cpu",
) -> Generator

Create a torch.Generator initialized with a given seed.

Parameters:

Name	Type	Description	Default
random_seed	int	Specifies a random seed.	1
device	device | str | None	Specifies the desired device for the generator.	'cpu'

Returns:

Type	Description
Generator	A PyTorch pseudo random number generator.

Example usage:

>>> import torch
>>> from redcat.utils.tensor import get_torch_generator
>>> generator = get_torch_generator(42)
>>> torch.rand(2, 4, generator=generator)
tensor([[...]])
>>> generator = get_torch_generator(42)
>>> torch.rand(2, 4, generator=generator)
tensor([[...]])

redcat.utils.tensor.permute_along_dim

permute_along_dim(
    tensor: Tensor, permutation: Tensor, dim: int = 0
) -> Tensor

Permutes the values of a tensor along a given dimension.

Parameters:

Name	Type	Description	Default
tensor	Tensor	Specifies the tensor to permute.	required
permutation	Tensor	Specifies the permutation to use on the tensor. The dimension of this tensor should be compatible with the shape of the tensor to permute.	required
dim	int	Specifies the dimension used to permute the tensor.	0

Returns:

Type	Description
Tensor	The permuted tensor.

Example usage:

>>> import torch
>>> from redcat.utils.tensor import permute_along_dim
>>> permute_along_dim(tensor=torch.arange(4), permutation=torch.tensor([0, 2, 1, 3]))
tensor([0, 2, 1, 3])
>>> permute_along_dim(
...     tensor=torch.arange(20).view(4, 5),
...     permutation=torch.tensor([0, 2, 1, 3]),
... )
tensor([[ 0,  1,  2,  3,  4],
        [10, 11, 12, 13, 14],
        [ 5,  6,  7,  8,  9],
        [15, 16, 17, 18, 19]])
>>> permute_along_dim(
...     tensor=torch.arange(20).view(4, 5),
...     permutation=torch.tensor([0, 4, 2, 1, 3]),
...     dim=1,
... )
tensor([[ 0,  4,  2,  1,  3],
        [ 5,  9,  7,  6,  8],
        [10, 14, 12, 11, 13],
        [15, 19, 17, 16, 18]])
>>> permute_along_dim(
...     tensor=torch.arange(20).view(2, 2, 5),
...     permutation=torch.tensor([0, 4, 2, 1, 3]),
...     dim=2,
... )
tensor([[[ 0,  4,  2,  1,  3],
         [ 5,  9,  7,  6,  8]],
        [[10, 14, 12, 11, 13],
         [15, 19, 17, 16, 18]]])

redcat.utils.tensor.to_tensor

to_tensor(
    data: BaseBatch | Sequence | Tensor | ndarray,
) -> Tensor

Convert the input to a torch.Tensor.

Parameters:

Name	Type	Description	Default
data	BaseBatch | Sequence | Tensor | ndarray	Specifies the data to convert to a tensor.	required

Returns:

Type	Description
Tensor	A tensor.

Example usage:

>>> from redcat.utils.tensor import to_tensor
>>> x = to_tensor([1, 2, 3, 4, 5])
>>> x
tensor([1, 2, 3, 4, 5])