erlab.interactive.imagetool.fastbinning

Fast parallelized averaging for multidimensional arrays.

This module provides a numba-based fast, parallelized version of nanmean that supports multiple axes. This enables efficient real-time multidimensional binning.

Module Attributes

NANMEAN_FUNCS

Mapping from array dimensions to axis combinations to corresponding functions.

Functions

fast_nanmean(a[, axis])	Compute the mean for floating point arrays while ignoring NaNs.
fast_nanmean_skipcheck(a, axis)	Compute the mean for specific floating point arrays while ignoring NaNs.

erlab.interactive.imagetool.fastbinning.fast_nanmean(a, axis=None)

Compute the mean for floating point arrays while ignoring NaNs.

Parameters:

• a (ndarray[Any, dtype[float32 | float64]]) – A numpy array of floats.

• axis (int | Collection[int] | None) – Axis or iterable of axis along which the means are computed. If None, the mean of the flattend array is computed.

Returns:

The calculated mean. The output array is always C-contiguous.

Return type:

numpy.ndarray or float

Notes

• Parallelization is only applied for N-dimensional arrays with N <= 4 and len(axis) < N.

• For calculating the average of a flattened array (axis = None or len(axis) == N), the numba implemenation of numpy.nanmean is used.

• For bigger N, numbagg.nanmean is used if numbagg is installed. Otherwise, the calculation falls back to numpy.nanmean.

• This function does not keep the input dimensions, i.e., the output is squeezed.

• For single precision input, the calculation is performed in double precision and converted back to single precision. This may lead to different results compared to numpy.nanmean.

erlab.interactive.imagetool.fastbinning.fast_nanmean_skipcheck(a, axis)

Compute the mean for specific floating point arrays while ignoring NaNs.

This is a version of fast_nanmean with near-zero overhead meant for internal use. Strict assumptions on the input parameters allow skipping some checks. Failure to meet these assumptions may lead to undefined behavior.

Parameters:

• a (ndarray[Any, dtype[float32 | float64]]) – A numpy array of floats. a.ndim must be one of 2, 3, and 4.

• axis (int | Collection[int]) – Axis or iterable of axis along which the means are computed. All elements must be nonnegative integers that are less than or equal to a.ndim, i.e., negative indexing is not allowed.

Returns:

The calculated mean. The output array is always C-contiguous.

Return type:

numpy.ndarray or float

erlab.interactive.imagetool.fastbinning.NANMEAN_FUNCS: dict[int, dict[int | frozenset[int], Callable]] = {2: {0: CPUDispatcher(<function _nanmean_2_0>), 1: CPUDispatcher(<function _nanmean_2_1>), frozenset({0}): CPUDispatcher(<function _nanmean_2_0>), frozenset({1}): CPUDispatcher(<function _nanmean_2_1>)}, 3: {0: CPUDispatcher(<function _nanmean_3_0>), 1: CPUDispatcher(<function _nanmean_3_1>), 2: CPUDispatcher(<function _nanmean_3_2>), frozenset({0, 1}): CPUDispatcher(<function _nanmean_3_01>), frozenset({0, 2}): CPUDispatcher(<function _nanmean_3_02>), frozenset({0}): CPUDispatcher(<function _nanmean_3_0>), frozenset({1, 2}): CPUDispatcher(<function _nanmean_3_12>), frozenset({1}): CPUDispatcher(<function _nanmean_3_1>), frozenset({2}): CPUDispatcher(<function _nanmean_3_2>)}, 4: {0: CPUDispatcher(<function _nanmean_4_0>), 1: CPUDispatcher(<function _nanmean_4_1>), 2: CPUDispatcher(<function _nanmean_4_2>), 3: CPUDispatcher(<function _nanmean_4_3>), frozenset({0, 1, 2}): CPUDispatcher(<function _nanmean_4_012>), frozenset({0, 1, 3}): CPUDispatcher(<function _nanmean_4_013>), frozenset({0, 1}): CPUDispatcher(<function _nanmean_4_01>), frozenset({0, 2, 3}): CPUDispatcher(<function _nanmean_4_023>), frozenset({0, 2}): CPUDispatcher(<function _nanmean_4_02>), frozenset({0, 3}): CPUDispatcher(<function _nanmean_4_03>), frozenset({0}): CPUDispatcher(<function _nanmean_4_0>), frozenset({1, 2, 3}): CPUDispatcher(<function _nanmean_4_123>), frozenset({1, 2}): CPUDispatcher(<function _nanmean_4_12>), frozenset({1, 3}): CPUDispatcher(<function _nanmean_4_13>), frozenset({1}): CPUDispatcher(<function _nanmean_4_1>), frozenset({2, 3}): CPUDispatcher(<function _nanmean_4_23>), frozenset({2}): CPUDispatcher(<function _nanmean_4_2>), frozenset({3}): CPUDispatcher(<function _nanmean_4_3>)}}

Mapping from array dimensions to axis combinations to corresponding functions.