Reducers

coola.reducers

Contain the reducer implementations.

coola.reducers.BaseBasicReducer

Bases: BaseReducer[T]

Extension of BaseReducer to check if the input sequence is empty before to call the reduction methods.

coola.reducers.BaseReducer

Bases: ABC, Generic[T]

Define the base class to implement a reducer.

Example usage:

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

coola.reducers.BaseReducer.max abstractmethod

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.

Example usage:

.. code-block:: pycon

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

coola.reducers.BaseReducer.mean abstractmethod

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 usage:

.. code-block:: pycon

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

coola.reducers.BaseReducer.median abstractmethod

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 usage:

.. code-block:: pycon

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

coola.reducers.BaseReducer.min abstractmethod

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 usage:

.. code-block:: pycon

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

coola.reducers.BaseReducer.quantile abstractmethod

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

Compute the quantiles.

Parameters:

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

Returns:

Type	Description
list[float]	The quantiles.

Raises:

Type	Description
EmptySequenceError	if the input sequence is empty.

Example usage:

.. code-block:: pycon

>>> from coola.reducers 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.reducers.BaseReducer.sort abstractmethod

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

Sorts the values.

Parameters:

Name	Type	Description	Default
values	T	The values.	required
descending	bool	The sorting order.	False

Returns:

Type	Description
list[int | float]	The sorted values.

Example usage:

.. code-block:: pycon

>>> from coola.reducers 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]

coola.reducers.BaseReducer.std abstractmethod

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 usage:

.. code-block:: pycon

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

coola.reducers.EmptySequenceError

Bases: Exception

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

coola.reducers.NativeReducer

Bases: BaseBasicReducer[T]

Implement a native reducer.

Example usage:

>>> from coola.reducers 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]

coola.reducers.NumpyReducer

Bases: BaseBasicReducer[T]

Implement a reducer based on NumPy functions.

Raises:

Type	Description
RuntimeError	if numpy is not installed.

Example usage:

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

coola.reducers.ReducerRegistry

Implement the reducer registry.

The registry is a class variable, so it is shared with all the instances of this class.

coola.reducers.ReducerRegistry.add_reducer classmethod

add_reducer(
    name: str, reducer: BaseReducer, exist_ok: bool = False
) -> None

Add a reducer to the registry.

Parameters:

Name	Type	Description	Default
name	str	The name of the reducer.	required
reducer	BaseReducer	The reducer.	required
exist_ok	bool	If False, RuntimeError is raised if the name already exists. This parameter should be set to True to overwrite the existing reducer.	False

Raises:

Type	Description
RuntimeError	if a reducer is already registered for the name and exist_ok=False.

Example usage:

>>> from coola.reducers import ReducerRegistry, NativeReducer
>>> ReducerRegistry.add_reducer("native", NativeReducer(), exist_ok=True)

coola.reducers.ReducerRegistry.available_reducers classmethod

available_reducers() -> tuple[str, ...]

Get the available reducers.

Returns:

Type	Description
tuple[str, ...]	The available reducers.

Example usage:

>>> from coola.reducers import ReducerRegistry
>>> ReducerRegistry.available_reducers()
('native', 'numpy', 'torch')

coola.reducers.ReducerRegistry.has_reducer classmethod

has_reducer(name: str) -> bool

Indicate if a reducer is registered for the given name.

Parameters:

Name	Type	Description	Default
name	str	The name to check.	required

Returns:

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

Example usage:

>>> from coola.reducers import ReducerRegistry
>>> ReducerRegistry.has_reducer("native")
True
>>> ReducerRegistry.has_reducer("missing")
False

coola.reducers.TorchReducer

Bases: BaseBasicReducer[T]

Implement a reducer based on torch functions.

Raises:

Type	Description
RuntimeError	if torch is not installed.

Example usage:

>>> from coola.reducers 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.reducers.auto_reducer

auto_reducer() -> BaseReducer

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

The "best" reducer is found by using the following rules: - If torch is available, use TorchReducer - If numpy is available, use NumpyReducer - Otherwise, use BasicReducer

Returns:

Type	Description
BaseReducer	The "best" reducer.

Example usage:

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