Base classes¶

redcat.BaseBatch ¶

Bases: Generic[T], ABC

Define the base class to implement a batch.

redcat.BaseBatch.batch_size `abstractmethod` `property` ¶

batch_size: int

The batch size.

redcat.BaseBatch.data `abstractmethod` `property` ¶

data: T

The data in the batch.

redcat.BaseBatch.allclose `abstractmethod` ¶

allclose(
    other: Any,
    rtol: float = 1e-05,
    atol: float = 1e-08,
    equal_nan: bool = False,
) -> bool

Indicate if two batches are equal within a tolerance or not.

Parameters:

Name	Type	Description	Default
`other`	`Any`	Specifies the value to compare.	required
`rtol`	`float`	Specifies the relative tolerance parameter.	`1e-05`
`atol`	`float`	Specifies the absolute tolerance parameter.	`1e-08`
`equal_nan`	`bool`	If `True`, then two `NaN`s will be considered equal.	`False`

Returns:

Type	Description
`bool`	`True` if the batches are equal within a tolerance, `False` otherwise.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch1 = BatchedArray(torch.ones(2, 3))
>>> batch2 = BatchedArray(torch.full((2, 3), 1.5))
>>> batch1.allclose(batch2, atol=1, rtol=0)
True

redcat.BaseBatch.allequal `abstractmethod` ¶

allequal(other: Any) -> bool

Indicate if two batches are equal or not.

Parameters:

Name	Type	Description	Default
`other`	`Any`	Specifies the value to compare.	required

Returns:

Type	Description
`bool`	`True` if the batches have the same size, elements and same batch dimension, `False` otherwise.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> BatchedArray(torch.ones(2, 3)).allequal(BatchedArray(torch.zeros(2, 3)))
False

redcat.BaseBatch.append `abstractmethod` ¶

append(other: BaseBatch) -> None

Append a new batch to the current batch along the batch dimension.

Parameters:

Name	Type	Description	Default
`other`	`BaseBatch`	Specifies the batch to append at the end of current batch.	required

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.ones((2, 3)))
>>> batch.append(BatchedArray(np.zeros((1, 3))))
>>> batch.append(BatchedArray(np.full((1, 3), 2.0)))
>>> batch
array([[1., 1., 1.],
       [1., 1., 1.],
       [0., 0., 0.],
       [2., 2., 2.]], batch_axis=0)

redcat.BaseBatch.chunk_along_batch `abstractmethod` ¶

chunk_along_batch(chunks: int) -> tuple[Self, ...]

Split the batch into chunks along the batch dimension.

Parameters:

Name	Type	Description	Default
`chunks`	`int`	Specifies the number of chunks.	required

Returns:

Type	Description
`tuple[Self, ...]`	The batch split into chunks along the batch dimension.

Raises:

Type	Description
`RuntimeError`	if the number of chunks is incorrect

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> BatchedArray(np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])).chunk_along_batch(
...     chunks=3
... )
(array([[0, 1], [2, 3]], batch_axis=0),
 array([[4, 5], [6, 7]], batch_axis=0),
 array([[8, 9]], batch_axis=0))

redcat.BaseBatch.clone `abstractmethod` ¶

clone() -> Self

Create a copy of the current batch.

Returns:

Type	Description
`Self`	A copy of the current batch.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.ones((2, 3)))
>>> batch_copy = batch.clone()
>>> batch_copy
array([[1., 1., 1.], [1., 1., 1.]], batch_axis=0)

redcat.BaseBatch.extend `abstractmethod` ¶

extend(other: Iterable[BaseBatch]) -> None

Extend the current batch by appending all the batches from the iterable.

This method should be used with batches of similar nature. For example, it is possible to extend a batch representing data as torch.Tensor by another batch representing data as torch.Tensor, but it is usually not possible to extend a batch representing data torch.Tensor by a batch representing data with a dictionary. Please check each implementation to know the supported batch implementations.

Parameters:

Name	Type	Description	Default
`other`	`Iterable[BaseBatch]`	Specifies the batches to append to the current batch.	required

Raises:

Type	Description
`TypeError`	if there is no available implementation for the input batch type.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.ones((2, 3)))
>>> batch.extend([BatchedArray(np.zeros((1, 3))), BatchedArray(np.full((1, 3), 2.0))])
>>> batch
array([[1., 1., 1.],
       [1., 1., 1.],
       [0., 0., 0.],
       [2., 2., 2.]], batch_axis=0)

redcat.BaseBatch.get_num_minibatches ¶

get_num_minibatches(
    batch_size: int, drop_last: bool = False
) -> int

Get the number of mini-batches for a given batch size.

Parameters:

Name	Type	Description	Default
`batch_size`	`int`	Specifies the target batch size of the mini-batches.	required
`drop_last`	`bool`	If `True`, the last batch is dropped if it is not full, otherwise it is returned.	`False`

Returns:

Type	Description
`int`	The number of mini-batches.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.arange(10))
>>> batch.get_num_minibatches(batch_size=4)
3
>>> batch.get_num_minibatches(batch_size=4, drop_last=True)
2

redcat.BaseBatch.index_select_along_batch `abstractmethod` ¶

index_select_along_batch(
    index: Tensor | Sequence[int],
) -> BaseBatch

Select data at the given indices along the batch dimension.

Parameters:

Name	Type	Description	Default
`index`	`Tensor \| Sequence[int]`	Specifies the indices to select.	required

Returns:

Type	Description
`BaseBatch`	A new batch which indexes `self` along the batch dimension using the entries in `index`.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]]))
>>> batch.index_select_along_batch([2, 4])
array([[4, 5], [8, 9]], batch_axis=0)
>>> batch.index_select_along_batch(np.array([4, 3, 2, 1, 0]))
array([[8, 9],
       [6, 7],
       [4, 5],
       [2, 3],
       [0, 1]], batch_axis=0)

redcat.BaseBatch.permute_along_batch `abstractmethod` ¶

permute_along_batch(
    permutation: Sequence[int] | Tensor,
) -> Self

Permutes the data/batch along the batch dimension.

Parameters:

Name	Type	Description	Default
`permutation`	`Sequence[int] \| Tensor`	Specifies the permutation to use on the data. The dimension of the permutation input should be compatible with the shape of the data.	required

Returns:

Type	Description
`Self`	A new batch with permuted data.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]]))
>>> batch.permute_along_batch([2, 1, 3, 0, 4])
array([[4, 5],
       [2, 3],
       [6, 7],
       [0, 1],
       [8, 9]], batch_axis=0)

redcat.BaseBatch.permute_along_batch_ `abstractmethod` ¶

permute_along_batch_(
    permutation: Sequence[int] | Tensor,
) -> None

Permutes the data/batch along the batch dimension.

Parameters:

Name	Type	Description	Default
`permutation`	`Sequence[int] \| Tensor`	Specifies the permutation to use on the data. The dimension of the permutation input should be compatible with the shape of the data.	required

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]]))
>>> batch.permute_along_batch_([2, 1, 3, 0, 4])
>>> batch
array([[4, 5],
       [2, 3],
       [6, 7],
       [0, 1],
       [8, 9]], batch_axis=0)

redcat.BaseBatch.select_along_batch ¶

select_along_batch(index: int) -> T

Select the batch along the batch dimension at the given index.

Parameters:

Name	Type	Description	Default
`index`	`int`	Specifies the index to select.	required

Returns:

Type	Description
`T`	The batch sliced along the batch dimension at the given index.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> BatchedArray(np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])).select_along_batch(2)
array([4, 5])

redcat.BaseBatch.shuffle_along_batch ¶

shuffle_along_batch(
    generator: Generator | None = None,
) -> Self

Shuffles the data/batch along the batch dimension.

Parameters:

Name	Type	Description	Default
`generator`	`Generator \| None`	Specifies an optional pseudo random number generator.	`None`

Returns:

Type	Description
`Self`	A new batch with shuffled data.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]]))
>>> batch.shuffle_along_batch()
array([[...]], batch_axis=0)

redcat.BaseBatch.shuffle_along_batch_ ¶

shuffle_along_batch_(
    generator: Generator | None = None,
) -> None

Shuffles the data/batch along the batch dimension.

Parameters:

Name	Type	Description	Default
`generator`	`Generator \| None`	Specifies an optional pseudo random number generator.	`None`

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]]))
>>> batch.shuffle_along_batch_()
>>> batch
array([[...]], batch_axis=0)

redcat.BaseBatch.slice_along_batch `abstractmethod` ¶

slice_along_batch(
    start: int = 0, stop: int | None = None, step: int = 1
) -> Self

Slices the batch in the batch dimension.

Parameters:

Name	Type	Description	Default
`start`	`int`	Specifies the index where the slicing of object starts.	`0`
`stop`	`int \| None`	Specifies the index where the slicing of object stops. `None` means last.	`None`
`step`	`int`	Specifies the increment between each index for slicing.	`1`

Returns:

Type	Description
`Self`	A slice of the current batch.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> BatchedArray(np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])).slice_along_batch(
...     start=2
... )
array([[4, 5],
       [6, 7],
       [8, 9]], batch_axis=0)
>>> BatchedArray(np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])).slice_along_batch(
...     stop=3
... )
array([[0, 1],
       [2, 3],
       [4, 5]], batch_axis=0)
>>> BatchedArray(np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])).slice_along_batch(
...     step=2
... )
array([[0, 1],
       [4, 5],
       [8, 9]], batch_axis=0)

redcat.BaseBatch.split_along_batch `abstractmethod` ¶

split_along_batch(
    split_size_or_sections: int | Sequence[int],
) -> tuple[Self, ...]

Split the batch into chunks along the batch dimension.

Parameters:

Name	Type	Description	Default
`split_size_or_sections`	`int \| Sequence[int]`	Specifies the size of a single chunk or list of sizes for each chunk.	required

Returns:

Type	Description
`tuple[Self, ...]`	The batch split into chunks along the batch dimension.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> BatchedArray(np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])).split_along_batch(2)
(array([[0, 1], [2, 3]], batch_axis=0),
 array([[4, 5], [6, 7]], batch_axis=0),
 array([[8, 9]], batch_axis=0))

redcat.BaseBatch.summary `abstractmethod` ¶

summary() -> str

Return a summary of the current batch.

Returns:

Type	Description
`str`	The summary of the current batch

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.ones((10, 2)))
>>> print(batch.summary())
BatchedArray(dtype=float64, shape=(10, 2), batch_axis=0)

redcat.BaseBatch.to_data `abstractmethod` ¶

to_data() -> Any

Return the internal data without the batch wrapper.

Returns:

Type	Description
`Any`	The internal data.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.ones((2, 3)))
>>> data = batch.to_data()
>>> data
array([[1., 1., 1.], [1., 1., 1.]])

redcat.BaseBatch.to_minibatches ¶

to_minibatches(
    batch_size: int,
    drop_last: bool = False,
    deepcopy: bool = False,
) -> Iterable[Self]

Get the mini-batches of the current batch.

Parameters:

Name	Type	Description	Default
`batch_size`	`int`	Specifies the target batch size of the mini-batches.	required
`drop_last`	`bool`	If `True`, the last batch is dropped if it is not full, otherwise it is returned.	`False`
`deepcopy`	`bool`	If `True`, a deepcopy of the batch is performed before to return the mini-batches. If `False`, each chunk is a view of the original batch/tensor. Using deepcopy allows a deterministic behavior when in-place operations are performed on the data.	`False`

Returns:

Type	Description
`Iterable[Self]`	The mini-batches.

Example usage:

>>> import numpy as np
>>> from redcat.ba import BatchedArray
>>> batch = BatchedArray(np.arange(20).reshape(10, 2))
>>> list(batch.to_minibatches(batch_size=4))
[array([[0, 1],
        [2, 3],
        [4, 5],
        [6, 7]], batch_axis=0),
 array([[ 8,  9],
        [10, 11],
        [12, 13],
        [14, 15]], batch_axis=0),
 array([[16, 17],
        [18, 19]], batch_axis=0)]
>>> list(batch.to_minibatches(batch_size=4, drop_last=True))
[array([[0, 1],
        [2, 3],
        [4, 5],
        [6, 7]], batch_axis=0),
 array([[ 8,  9],
        [10, 11],
        [12, 13],
        [14, 15]], batch_axis=0)]

Base classes¶

redcat.BaseBatch ¶

redcat.BaseBatch.batch_size abstractmethod property ¶

redcat.BaseBatch.data abstractmethod property ¶

redcat.BaseBatch.allclose abstractmethod ¶

redcat.BaseBatch.allequal abstractmethod ¶

redcat.BaseBatch.append abstractmethod ¶

redcat.BaseBatch.chunk_along_batch abstractmethod ¶

redcat.BaseBatch.clone abstractmethod ¶

redcat.BaseBatch.extend abstractmethod ¶

redcat.BaseBatch.get_num_minibatches ¶

redcat.BaseBatch.index_select_along_batch abstractmethod ¶

redcat.BaseBatch.permute_along_batch abstractmethod ¶

redcat.BaseBatch.permute_along_batch_ abstractmethod ¶

redcat.BaseBatch.select_along_batch ¶

redcat.BaseBatch.shuffle_along_batch ¶

redcat.BaseBatch.shuffle_along_batch_ ¶

redcat.BaseBatch.slice_along_batch abstractmethod ¶

redcat.BaseBatch.split_along_batch abstractmethod ¶

redcat.BaseBatch.summary abstractmethod ¶

redcat.BaseBatch.to_data abstractmethod ¶

redcat.BaseBatch.to_minibatches ¶

redcat.BaseBatch.batch_size `abstractmethod` `property` ¶

redcat.BaseBatch.data `abstractmethod` `property` ¶

redcat.BaseBatch.allclose `abstractmethod` ¶

redcat.BaseBatch.allequal `abstractmethod` ¶

redcat.BaseBatch.append `abstractmethod` ¶

redcat.BaseBatch.chunk_along_batch `abstractmethod` ¶

redcat.BaseBatch.clone `abstractmethod` ¶

redcat.BaseBatch.extend `abstractmethod` ¶

redcat.BaseBatch.index_select_along_batch `abstractmethod` ¶

redcat.BaseBatch.permute_along_batch `abstractmethod` ¶

redcat.BaseBatch.permute_along_batch_ `abstractmethod` ¶

redcat.BaseBatch.slice_along_batch `abstractmethod` ¶

redcat.BaseBatch.split_along_batch `abstractmethod` ¶

redcat.BaseBatch.summary `abstractmethod` ¶

redcat.BaseBatch.to_data `abstractmethod` ¶