util#

Utilitary functions.

class Dispatcher(name, numpy=None, dask=None, xarray=None)#

Bases: object

Choose a function depending on input type.

When a mapper instance is created (for a specific algorithm), each input type is associated to an implementation that supports it. No all mappers need to contain an implementation for every possible type. The mapper will give an appropriate message error if a input type is unsupported, or if the needed library is not installed.

The right implementation is obtained with get_func().

This class can choose between “numpy” and “dask”. If needed, it could be modified to include support for more input types, cudy for GPU implementations for instance. The inspiration for this process is makepath/xarray-spatial and it shows such examples.

Parameters:

name (str) – Name of the algorithm. For clearer error messages.
numpy (Callable | None)
dask (Callable | None)
xarray (Callable | None)

get(kind)#

Return a func or raise error if no implementation is registered.

Parameters:: kind (str)
Return type:: Callable

get_func(array)#

Return implementation for a specific input object.

Parameters:: array (Any)
Return type:: Callable

class KwargsWrap(func, arg_names)#

Bases: object

A thin wrapper that transform kwargs into positional args.

Fonctions compiled with numba.guvectorize only accept positional arguments, but (as I understand it) Dask treats positional arguments as chunked data. Use this wrapper to transform kwargs into positional arguments: Dask will see keyword arguments, but the fonction will receive positional arguments.

The could be written as a simpler function, but it could not be pickled for dask.distributed (the wrapper would be a locally defined function).

Parameters:

func (Callable) – Compiled function.
arg_names (Sequence[str]) – List of the keyword arguments names, in order they should be passed to func.

apply_vectorized(func, input_field, axes=None, n_dim_core=2, **kwargs)#

Get a signature to give to numpy.vectorize. Deal with keyword arguments.

Parameters:

func (Callable[[ndarray[_Size, _DTin]], ndarray[_Size, _DTout]]) – Function to apply. Must take a single array with n_dim_core axes and return a single output array of the same shape.
input_field (ndarray[_Size, _DTin]) – The input array.
axes (Sequence[int] | None) – The core dimensions indices. If None the last axes of the array are taken.
n_dim_core (int) – The number of core dimensions.
kwargs – Passed to the function.

Returns:

A single output array. Has the same shape and axes order as the input.

Return type:

ndarray[_Size, _DTout]

axes_help = 'Indices of the the y/lat and x/lon axes on which to work. If None (default), the last\ntwo axes are used.'#: Help string for the recurring ‘axes’ argument.

detect_bins_shift(input_field)#

Detect bins shift from scale factor if present.

Parameters:: input_field (DataArray)
Return type:: float

dims_help = "Names of the dimensions along which to apply the algorithm. Order is irrelevant, no\nreordering will be made between the two dimensions. If the `window_size` argument is\ngiven as a mapping, its keys are used instead. If not specified, is taken as module-wide\nvariable :data:`DEFAULT_DIMS` which defaults to ``{'lat', 'lon'}``."#: Help string for the recurring ‘dims’ argument.

doc(doc_dict, remove=None, **change)#

Set docstring automatically.

For when multiple function have near identical docstrings (variants for different input types for instance). It uses numpy doc style, to have legible interactive help.

Parameters:

doc_dict (dict[str, str]) – Dictionnary containing the documentation. The first line is kept from the decorated function.Key ‘init’ holds the initial paragraph. Keys ‘returns’ and ‘rtype’ are added to corresponding roles. Other keys are added as parameters. Any key ending in ‘_type’ is added to a parameter type role.
remove (Collection[str] | None) – Keys to remove from doc_dict.
change (str) – Keys to add or change.

Return type:

Callable[[Function], Function]

get_axes_kwarg(signature, axes, order='y,x')#

Format axes argument for a ufunc from a single sequence of ints.

Parameters:

signature (str) – Signature of the universal function.
axes (Sequence[int]) – Core axes indices in the input array.
order (str) – Order of core dimensions for axes.

Returns:

Argument formatted for the axes keyword argument of a ufunc.

Return type:

list[tuple[int, …]]

get_dims_and_window_size(input_field, dims, window_size, default_dims)#

Process window_size and dims arguments.

Parameters:

input_field (DataArray | Dataset)
dims (Collection[Hashable] | None)
window_size (int | Mapping[Hashable, int])
default_dims (list[Hashable])

Return type:

tuple[list[Hashable], dict[Hashable, int]]

get_window_reach(window_size)#

Return window reach as a list.

Parameters:: window_size (int | Sequence[int])
Return type:: list[int]

is_chunked_core(input_field, axes)#

Return whether the array is chunked along the core dimensions.

Parameters:

axes (Sequence[int]) – Indices of the core dimensions of the computation.
input_field (DaskArray)

Return type:

bool

module_available(module)#

Check whether a module is installed without importing it.

Use this for a lightweight check and lazy imports.

Parameters:: module (str)
Return type:: bool

ufunc_kwargs_help = 'See available kwargs for universal functions at\n:external+numpy:ref:`c-api.generalized-ufuncs`.'#: Help string for the recurring ‘kwargs’ argument for ufuncs.