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

A dictionary that maps the number of dimensions of the input array to a dictionary of functions that calculate the mean along specific axes.

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.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>)}}

A dictionary that maps the number of dimensions of the input array to a dictionary of functions that calculate the mean along specific axes. The keys of the inner dictionary are integers or frozensets of integers that represent the axes along which the mean is to be calculated.

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

Compute the mean for floating point arrays while ignoring NaNs.

Parameters:

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

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

Returns:

numpy.ndarray or float – The calculated mean. The output array is always C-contiguous.

Return type:

ndarray[tuple[Any, …], dtype[float32 | float64]] | float64

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 implementation 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. See the parameter descriptions for allowed input values.

Parameters:

• a (ndarray[tuple[Any, ...], dtype[float32 | float64]] | Array) – 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:

numpy.ndarray or float – The calculated mean. The output array is always C-contiguous.

Return type:

ndarray[tuple[Any, …], dtype[float32 | float64]] | float64 | Array

Note

This function does not check for the validity of the input parameters. Invalid input may lead to obscure errors or silently produce incorrect results.