Reducer

coola.reducer

Reduction utilities for computing statistics over numeric sequences.

A reducer turns a one-dimensional sequence of real numbers into a statistic (max, min, mean, median, std, quantile) or into a sorted list. NativeReducer, NumpyReducer and TorchReducer have the same methods, the same errors and the same result types (a Python int or float), so the backend can be swapped. The statistics raise EmptySequenceError on an empty input, NaN propagates whatever its position, the input is never modified, and importing this package does not import NumPy or PyTorch.

Not guaranteed: bit-identical floating point results across backends, sums that exceed the range of a float, and number types other than int and float.

coola.reducer.BaseReducer

Bases: ABC, Generic[T]

Define the base class to implement a reducer.

Example

>>> from coola.reducer import NumpyReducer
>>> reducer = NumpyReducer()
>>> reducer.max([-2, -1, 0, 1, 2])
2
>>> reducer.median([-2, -1, 0, 1, 2])
0
>>> reducer.sort([2, 1, -2, 3, 0])
[-2, 0, 1, 2, 3]

coola.reducer.BaseReducer.max

max(values: T) -> int | float

Compute the maximum value.

Parameters:

Name	Type	Description	Default
values	T	The values.	required

Returns:

Type	Description
int | float	The maximum value.

Raises:

Type	Description
EmptySequenceError	if the input sequence is empty.
TypeError	if the input is an iterator (e.g. a generator).

Example

>>> from coola.reducer import TorchReducer
>>> reducer = TorchReducer()
>>> reducer.max([-2, -1, 0, 1, 2])
2

coola.reducer.BaseReducer.mean

mean(values: T) -> float

Compute the mean value.

Parameters:

Name	Type	Description	Default
values	T	The values.	required

Returns:

Type	Description
float	The mean value.

Raises:

Type	Description
EmptySequenceError	if the input sequence is empty.

Example

>>> from coola.reducer import TorchReducer
>>> reducer = TorchReducer()
>>> reducer.mean([-2, -1, 0, 1, 2])
0.0

coola.reducer.BaseReducer.median

median(values: T) -> int | float

Compute the median value.

Parameters:

Name	Type	Description	Default
values	T	The values.	required

Returns:

Type	Description
int | float	The median value.

Raises:

Type	Description
EmptySequenceError	if the input sequence is empty.

Example

>>> from coola.reducer import TorchReducer
>>> reducer = TorchReducer()
>>> reducer.median([-2, -1, 0, 1, 2])
0

coola.reducer.BaseReducer.min

min(values: T) -> int | float

Compute the minimum value.

Parameters:

Name	Type	Description	Default
values	T	The values.	required

Returns:

Type	Description
int | float	The minimum value.

Raises:

Type	Description
EmptySequenceError	if the input sequence is empty.

Example

>>> from coola.reducer import TorchReducer
>>> reducer = TorchReducer()
>>> reducer.min([-2, -1, 0, 1, 2])
-2

coola.reducer.BaseReducer.quantile

quantile(
    values: T, quantiles: Sequence[float]
) -> list[float]

Compute the quantiles.

Parameters:

Name	Type	Description	Default
values	T	The values.	required
quantiles	Sequence[float]	The quantile values in the range [0, 1].	required

Returns:

Type	Description
list[float]	The quantiles.

Raises:

Type	Description
ValueError	if a quantile is not in the range [0, 1] (or is NaN). This is checked before the values.
EmptySequenceError	if the input sequence is empty.

Example

>>> from coola.reducer import TorchReducer
>>> reducer = TorchReducer()
>>> reducer.quantile([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10], (0.2, 0.5, 0.9))
[2.0, 5.0, 9.0]

coola.reducer.BaseReducer.sort

sort(
    values: T, *, descending: bool = False
) -> list[int | float]

Sort the values.

Parameters:

Name	Type	Description	Default
values	T	The values.	required
descending	bool	If True, sorts in descending order. Defaults to False (ascending order).	False

Returns:

Type	Description
list[int | float]	The sorted values. An empty input returns an empty list,
list[int | float]	unlike the other reduction methods.

Example

>>> from coola.reducer import TorchReducer
>>> reducer = TorchReducer()
>>> reducer.sort([2, 1, -2, 3, 0])
[-2, 0, 1, 2, 3]
>>> reducer.sort([2, 1, -2, 3, 0], descending=True)
[3, 2, 1, 0, -2]
>>> reducer.sort([])
[]

coola.reducer.BaseReducer.std

std(values: T) -> float

Compute the standard deviation.

Parameters:

Name	Type	Description	Default
values	T	The values.	required

Returns:

Type	Description
float	The standard deviation.

Raises:

Type	Description
EmptySequenceError	if the input sequence is empty.

Example

>>> from coola.reducer import TorchReducer
>>> reducer = TorchReducer()
>>> reducer.std([-2, -1, 0, 1, 2])
1.581138...

coola.reducer.EmptySequenceError

Bases: ValueError

Raise when the sequence is empty because it is not possible to reduce an empty sequence.

coola.reducer.NativeReducer

Bases: InlineDisplayMixin, BaseReducer[Sequence[float]]

Implement a native reducer.

Example

>>> from coola.reducer import NativeReducer
>>> reducer = NativeReducer()
>>> reducer.max([-2, -1, 0, 1, 2])
2
>>> reducer.median([-2, -1, 0, 1, 2])
0
>>> reducer.sort([2, 1, -2, 3, 0])
[-2, 0, 1, 2, 3]
>>> reducer.max([1.0, float("nan"), 2.0])
nan

coola.reducer.NumpyReducer

Bases: InlineDisplayMixin, BaseReducer['Sequence[float] | np.ndarray']

Implement a reducer based on NumPy functions.

Raises:

Type	Description
MissingPackageError	if numpy is not installed.

Example

>>> from coola.reducer import NumpyReducer
>>> reducer = NumpyReducer()
>>> reducer.max([-2, -1, 0, 1, 2])
2
>>> reducer.median([-2, -1, 0, 1, 2])
0
>>> reducer.sort([2, 1, -2, 3, 0])
[-2, 0, 1, 2, 3]

coola.reducer.TorchReducer

Bases: InlineDisplayMixin, BaseReducer['Sequence[float] | torch.Tensor']

Implement a reducer based on torch functions.

Raises:

Type	Description
MissingPackageError	if torch is not installed.

Example

>>> from coola.reducer import TorchReducer
>>> reducer = TorchReducer()
>>> reducer.max([-2, -1, 0, 1, 2])
2
>>> reducer.median([-2, -1, 0, 1, 2])
0
>>> reducer.sort([2, 1, -2, 3, 0])
[-2, 0, 1, 2, 3]

coola.reducer.auto_reducer

auto_reducer() -> BaseReducer[Any]

Find the "best" reducer to used based on the installed packages.

The "best" reducer is the fastest one that is installed for plain Python sequences. It is found by using the following rules: - If numpy is available, use NumpyReducer - Otherwise, use NativeReducer

TorchReducer is never chosen implicitly: for a list, it is slower than NumpyReducer (the values are converted to a tensor first) and importing torch is slow. Create a TorchReducer explicitly to reduce tensors that live on a device. The rules do not look at the values. NumpyReducer fails for an integer that does not fit in 64 bits: use NativeReducer for arbitrary precision integers.

Returns:

Type	Description
BaseReducer[Any]	The "best" reducer.

Example

>>> from coola.reducer import auto_reducer
>>> reducer = auto_reducer()