computation

batcharray.computation

Contain the computation models.

batcharray.computation.ArrayComputationModel

Bases: BaseComputationModel[ndarray]

Implement a computation model for numpy.ndarrays.

batcharray.computation.AutoComputationModel

Bases: BaseComputationModel[T]

Implement a computation model that automatically finds the right computation model based on the array type.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import AutoComputationModel
>>> comp_model = AutoComputationModel()
>>> arrays = [
...     np.array([[0, 1, 2], [4, 5, 6]]),
...     np.array([[10, 11, 12], [13, 14, 15]]),
... ]
>>> out = comp_model.concatenate(arrays, axis=0)
>>> out
array([[ 0,  1,  2],
       [ 4,  5,  6],
       [10, 11, 12],
       [13, 14, 15]])

batcharray.computation.AutoComputationModel.add_computation_model classmethod

add_computation_model(
    array_type: type[ndarray],
    comp_model: BaseComputationModel[T],
    exist_ok: bool = False,
) -> None

Add a computation model for a given array type.

Parameters:

Name	Type	Description	Default
array_type	type[ndarray]	The array type.	required
comp_model	BaseComputationModel[T]	The computation model to use for the given array type.	required
exist_ok	bool	If False, RuntimeError is raised if the data type already exists. This parameter should be set to True to overwrite the computation model for an array type.	False

Raises:

Type	Description
RuntimeError	if a computation model is already registered for the array type and exist_ok=False.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import AutoComputationModel, ArrayComputationModel
>>> AutoComputationModel.add_computation_model(
...     np.ndarray, ArrayComputationModel(), exist_ok=True
... )

batcharray.computation.AutoComputationModel.find_computation_model classmethod

find_computation_model(
    array_type: type[ndarray],
) -> BaseComputationModel[T]

Find the computation model associated to an array type.

Parameters:

Name	Type	Description	Default
array_type	type[ndarray]	The array type.	required

Returns:

Type	Description
BaseComputationModel[T]	The computation model associated to the array type.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import AutoComputationModel
>>> AutoComputationModel.find_computation_model(np.ndarray)
ArrayComputationModel()
>>> AutoComputationModel.find_computation_model(np.ma.MaskedArray)
MaskedArrayComputationModel()

batcharray.computation.AutoComputationModel.has_computation_model classmethod

has_computation_model(array_type: type[ndarray]) -> bool

Indicate if a computation model is registered for the given array type.

Parameters:

Name	Type	Description	Default
array_type	type[ndarray]	The array type.	required

Returns:

Type	Description
bool	True if a computation model is registered, otherwise False.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import AutoComputationModel
>>> AutoComputationModel.has_computation_model(np.ndarray)
True
>>> AutoComputationModel.has_computation_model(str)
False

batcharray.computation.BaseComputationModel

Bases: ABC, Generic[T]

Base class for computation models and defines interface methods.

This class is public and should be used for other custom derived computation models.

batcharray.computation.BaseComputationModel.argmax abstractmethod

argmax(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the array of indices of the maximum values along the given axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the argmax are computed. The default (None) is to compute the argmax along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	The array of indices of the maximum values along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import ArrayComputationModel
>>> comp_model = ArrayComputationModel()
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = comp_model.argmax(array, axis=0)
>>> out
array([4, 4])
>>> out = comp_model.argmax(array, axis=1)
>>> out
array([1, 1, 1, 1, 1])
>>> out = comp_model.argmax(array, axis=0, keepdims=True)
>>> out
array([[4, 4]])

batcharray.computation.BaseComputationModel.argmin abstractmethod

argmin(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the array of indices of the minimum values along the given axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the argmin are computed. The default (None) is to compute the argmin along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	The array of indices of the minimum values along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import ArrayComputationModel
>>> comp_model = ArrayComputationModel()
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = comp_model.argmin(array, axis=0)
>>> out
array([0, 0])
>>> out = comp_model.argmin(array, axis=1)
>>> out
array([0, 0, 0, 0, 0])
>>> out = comp_model.argmin(array, axis=0, keepdims=True)
>>> out
array([[0, 0]])

batcharray.computation.BaseComputationModel.argsort abstractmethod

argsort(
    arr: T,
    axis: int | None = None,
    *,
    kind: SortKind | None = None
) -> T

Return the indices that sort an array along the given axis in ascending order by value.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the minimum values are computed. The default (None) is to compute the minimum along a flattened version of the array.	None
kind	SortKind | None	Sorting algorithm. The default is quicksort. Note that both stable and mergesort use timsort under the covers and, in general, the actual implementation will vary with datatype. The mergesort option is retained for backwards compatibility.	None

Returns:

Type	Description
T	The indices that sort the array along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import ArrayComputationModel
>>> comp_model = ArrayComputationModel()
>>> array = np.array([[3, 5, 0, 2, 4], [4, 7, 8, 9, 5], [7, 5, 8, 9, 0]])
>>> out = comp_model.argsort(array, axis=0)
>>> out
array([[0, 0, 0, 0, 2],
       [1, 2, 1, 1, 0],
       [2, 1, 2, 2, 1]])
>>> out = comp_model.argsort(array, axis=1)
>>> out
array([[2, 3, 0, 4, 1],
       [0, 4, 1, 2, 3],
       [4, 1, 0, 2, 3]])

batcharray.computation.BaseComputationModel.concatenate abstractmethod

concatenate(
    arrays: Sequence[T],
    axis: int | None = None,
    *,
    dtype: DTypeLike = None
) -> T

Concatenate a sequence of arrays along an existing axis.

Parameters:

Name	Type	Description	Default
arrays	Sequence[T]	The arrays to concatenate.	required
axis	int | None	The axis along which the arrays will be joined. If axis is None, arrays are flattened before use.	None
dtype	DTypeLike	If provided, the destination array will have this data type.	None

Returns:

Type	Description
T	The concatenated array.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import ArrayComputationModel
>>> comp_model = ArrayComputationModel()
>>> arrays = [
...     np.array([[0, 1, 2], [4, 5, 6]]),
...     np.array([[10, 11, 12], [13, 14, 15]]),
... ]
>>> out = comp_model.concatenate(arrays, axis=0)
>>> out
array([[ 0,  1,  2],
       [ 4,  5,  6],
       [10, 11, 12],
       [13, 14, 15]])
>>> out = comp_model.concatenate(arrays, axis=1)
>>> out
array([[ 0,  1,  2, 10, 11, 12],
       [ 4,  5,  6, 13, 14, 15]])

batcharray.computation.BaseComputationModel.max abstractmethod

max(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the maximum along the specified axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the maximum values are computed. The default (None) is to compute the maximum along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	The maximum of the input array along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import ArrayComputationModel
>>> comp_model = ArrayComputationModel()
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = comp_model.max(array, axis=0)
>>> out
array([8, 9])
>>> out = comp_model.max(array, axis=1)
>>> out
array([1, 3, 5, 7, 9])
>>> out = comp_model.max(array, axis=0, keepdims=True)
>>> out
array([[8, 9]])

batcharray.computation.BaseComputationModel.mean abstractmethod

mean(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the mean along the specified axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the means are computed. The default (None) is to compute the mean along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	A new array holding the result. If the input contains integers or floats smaller than np.float64, then the output data-type is np.float64. Otherwise, the data-type of the output is the same as that of the input.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import ArrayComputationModel
>>> comp_model = ArrayComputationModel()
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = comp_model.mean(array, axis=0)
>>> out
array([4., 5.])
>>> out = comp_model.mean(array, axis=1)
>>> out
array([0.5, 2.5, 4.5, 6.5, 8.5])
>>> out = comp_model.mean(array, axis=0, keepdims=True)
>>> out
array([[4., 5.]])

batcharray.computation.BaseComputationModel.median abstractmethod

median(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the median along the specified axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the medians are computed. The default (None) is to compute the median along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	A new array holding the result. If the input contains integers or floats smaller than np.float64, then the output data-type is np.float64. Otherwise, the data-type of the output is the same as that of the input.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import ArrayComputationModel
>>> comp_model = ArrayComputationModel()
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = comp_model.median(array, axis=0)
>>> out
array([4., 5.])
>>> out = comp_model.median(array, axis=1)
>>> out
array([0.5, 2.5, 4.5, 6.5, 8.5])
>>> out = comp_model.median(array, axis=0, keepdims=True)
>>> out
array([[4., 5.]])

batcharray.computation.BaseComputationModel.min abstractmethod

min(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the minimum along the specified axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the minimum values are computed. The default (None) is to compute the minimum along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	The minimum of the input array along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import ArrayComputationModel
>>> comp_model = ArrayComputationModel()
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = comp_model.min(array, axis=0)
>>> out
array([0, 1])
>>> out = comp_model.min(array, axis=1)
>>> out
array([0, 2, 4, 6, 8])
>>> out = comp_model.min(array, axis=0, keepdims=True)
>>> out
array([[0, 1]])

batcharray.computation.BaseComputationModel.sort abstractmethod

sort(
    arr: T,
    axis: int | None = None,
    *,
    kind: SortKind | None = None
) -> T

Sort the elements of the input array along the batch axis in ascending order by value.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the minimum values are computed. The default (None) is to compute the minimum along a flattened version of the array.	None
kind	SortKind | None	Sorting algorithm. The default is quicksort. Note that both stable and mergesort use timsort under the covers and, in general, the actual implementation will vary with datatype. The mergesort option is retained for backwards compatibility.	None

Returns:

Type	Description
T	The sorted array along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import ArrayComputationModel
>>> comp_model = ArrayComputationModel()
>>> array = np.array([[3, 5, 0, 2, 4], [4, 7, 8, 8, 5], [8, 5, 8, 8, 0]])
>>> out = comp_model.sort(array, axis=0)
>>> out
array([[3, 5, 0, 2, 0],
       [4, 5, 8, 8, 4],
       [8, 7, 8, 8, 5]])
>>> out = comp_model.sort(array, axis=1)
>>> out
array([[0, 2, 3, 4, 5],
       [4, 5, 7, 8, 8],
       [0, 5, 8, 8, 8]])

batcharray.computation.MaskedArrayComputationModel

Bases: BaseComputationModel[MaskedArray]

Implement a computation model for numpy.ma.MaskedArrays.

batcharray.computation.argmax

argmax(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the array of indices of the maximum values along the given axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the argmax are computed. The default (None) is to compute the argmax along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	The array of indices of the maximum values along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import argmax
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = argmax(array, axis=0)
>>> out
array([4, 4])
>>> out = argmax(array, axis=1)
>>> out
array([1, 1, 1, 1, 1])
>>> out = argmax(array, axis=0, keepdims=True)
>>> out
array([[4, 4]])

batcharray.computation.argmin

argmin(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the array of indices of the minimum values along the given axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the argmin are computed. The default (None) is to compute the argmin along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	The array of indices of the minimum values along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import argmin
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = argmin(array, axis=0)
>>> out
array([0, 0])
>>> out = argmin(array, axis=1)
>>> out
array([0, 0, 0, 0, 0])
>>> out = argmin(array, axis=0, keepdims=True)
>>> out
array([[0, 0]])

batcharray.computation.argsort

argsort(
    arr: T,
    axis: int | None = None,
    *,
    kind: SortKind | None = None
) -> T

Return the indices that sort an array along the given axis in ascending order by value.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the minimum values are computed. The default (None) is to compute the minimum along a flattened version of the array.	None
kind	SortKind | None	Sorting algorithm. The default is quicksort. Note that both stable and mergesort use timsort under the covers and, in general, the actual implementation will vary with datatype. The mergesort option is retained for backwards compatibility.	None

Returns:

Type	Description
T	The indices that sort the array along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import ArrayComputationModel
>>> comp_model = ArrayComputationModel()
>>> array = np.array([[3, 5, 0, 2, 4], [4, 7, 8, 9, 5], [7, 5, 8, 9, 0]])
>>> out = comp_model.argsort(array, axis=0)
>>> out
array([[0, 0, 0, 0, 2],
       [1, 2, 1, 1, 0],
       [2, 1, 2, 2, 1]])
>>> out = comp_model.argsort(array, axis=1)
>>> out
array([[2, 3, 0, 4, 1],
       [0, 4, 1, 2, 3],
       [4, 1, 0, 2, 3]])

batcharray.computation.concatenate

concatenate(
    arrays: Sequence[T],
    axis: int | None = None,
    *,
    dtype: DTypeLike = None
) -> T

Concatenate a sequence of arrays along an existing axis.

Parameters:

Name	Type	Description	Default
arrays	Sequence[T]	The arrays to concatenate.	required
axis	int | None	The axis along which the arrays will be joined. If axis is None, arrays are flattened before use.	None
dtype	DTypeLike	If provided, the destination array will have this data type.	None

Returns:

Type	Description
T	The concatenated array.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import concatenate
>>> arrays = [
...     np.array([[0, 1, 2], [4, 5, 6]]),
...     np.array([[10, 11, 12], [13, 14, 15]]),
... ]
>>> out = concatenate(arrays, axis=0)
>>> out
array([[ 0,  1,  2],
       [ 4,  5,  6],
       [10, 11, 12],
       [13, 14, 15]])
>>> out = concatenate(arrays, axis=1)
>>> out
array([[ 0,  1,  2, 10, 11, 12],
       [ 4,  5,  6, 13, 14, 15]])

batcharray.computation.max

max(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the maximum along the specified axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the maximum values are computed. The default (None) is to compute the maximum along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	The maximum of the input array along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import max
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = max(array, axis=0)
>>> out
array([8, 9])
>>> out = max(array, axis=1)
>>> out
array([1, 3, 5, 7, 9])
>>> out = max(array, axis=0, keepdims=True)
>>> out
array([[8, 9]])

batcharray.computation.mean

mean(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the mean along the specified axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the means are computed. The default (None) is to compute the mean along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	A new array holding the result. If the input contains integers or floats smaller than np.float64, then the output data-type is np.float64. Otherwise, the data-type of the output is the same as that of the input.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import mean
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = mean(array, axis=0)
>>> out
array([4., 5.])
>>> out = mean(array, axis=1)
>>> out
array([0.5, 2.5, 4.5, 6.5, 8.5])
>>> out = mean(array, axis=0, keepdims=True)
>>> out
array([[4., 5.]])

batcharray.computation.median

median(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the median along the specified axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the medians are computed. The default (None) is to compute the median along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	A new array holding the result. If the input contains integers or floats smaller than np.float64, then the output data-type is np.float64. Otherwise, the data-type of the output is the same as that of the input.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import median
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = median(array, axis=0)
>>> out
array([4., 5.])
>>> out = median(array, axis=1)
>>> out
array([0.5, 2.5, 4.5, 6.5, 8.5])
>>> out = median(array, axis=0, keepdims=True)
>>> out
array([[4., 5.]])

batcharray.computation.min

min(
    arr: T,
    axis: int | None = None,
    *,
    keepdims: bool = False
) -> T

Return the minimum along the specified axis.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the minimum values are computed. The default (None) is to compute the minimum along a flattened version of the array.	None
keepdims	bool	If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.	False

Returns:

Type	Description
T	The minimum of the input array along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import min
>>> array = np.array([[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]])
>>> out = min(array, axis=0)
>>> out
array([0, 1])
>>> out = min(array, axis=1)
>>> out
array([0, 2, 4, 6, 8])
>>> out = min(array, axis=0, keepdims=True)
>>> out
array([[0, 1]])

batcharray.computation.register_computation_models

register_computation_models() -> None

Register computation models to AutoComputationModel.

Example usage:

>>> from batcharray.computation import AutoComputationModel, register_computation_models
>>> register_computation_models()
>>> comp_model = AutoComputationModel()
>>> comp_model
AutoComputationModel(
  ...
)

batcharray.computation.sort

sort(
    arr: T,
    axis: int | None = None,
    *,
    kind: SortKind | None = None
) -> T

Sort the elements of the input array along the batch axis in ascending order by value.

Parameters:

Name	Type	Description	Default
arr	T	The input array.	required
axis	int | None	Axis along which the minimum values are computed. The default (None) is to compute the minimum along a flattened version of the array.	None
kind	SortKind | None	Sorting algorithm. The default is quicksort. Note that both stable and mergesort use timsort under the covers and, in general, the actual implementation will vary with datatype. The mergesort option is retained for backwards compatibility.	None

Returns:

Type	Description
T	The sorted array along the given axis.

Example usage:

>>> import numpy as np
>>> from batcharray.computation import sort
>>> array = np.array([[3, 5, 0, 2, 4], [4, 7, 8, 8, 5], [8, 5, 8, 8, 0]])
>>> out = sort(array, axis=0)
>>> out
array([[3, 5, 0, 2, 0],
       [4, 5, 8, 8, 4],
       [8, 7, 8, 8, 5]])
>>> out = sort(array, axis=1)
>>> out
array([[0, 2, 3, 4, 5],
       [4, 5, 7, 8, 8],
       [0, 5, 8, 8, 8]])