movement.utils.broadcasting

Description

Broadcasting operations across xarray.DataArray dimensions.

This module essentially provides an equivalent functionality to numpy.apply_along_axis, but for xarray.DataArray objects. This functionality is provided as a decorator, so it can be applied to both functions within the package and be available to users who would like to use it in their analysis. In essence; suppose that we have a function which takes a 1D-slice of a xarray.DataArray and returns either a scalar value, or another 1D array. Typically, one would either have to call this function successively in a for loop, looping over all the 1D slices in a xarray.DataArray that need to be examined, or re-write the function to be able to broadcast along the necessary dimension of the data structure.

The make_broadcastable decorator takes care of the latter piece of work, allowing us to write functions that operate on 1D slices, then apply this decorator to have them work across xarray.DataArray dimensions. The function

>>> def my_function(input_1d, *args, **kwargs):
...     # do something
...     return scalar_or_1d_output

which previously only worked with 1D-slices can be decorated

>>> @make_broadcastable()
... def my_function(input_1d, *args, **kwargs):
...     # do something
...     return scalar_or_1d_output

effectively changing its call signature to

>>> def my_function(data_array, *args, dimension, **kwargs):
...     # do my_function, but do it to all the slices
...     # along the dimension of data_array.
...     return data_array_output

which will perform the action of my_function along the dimension given. The *args and **kwargs retain their original interpretations from my_function too.

Functions

apply_along_da_axis	Apply a function f across dimension of data.
broadcastable_method	Broadcast a class method along a xarray.DataArray dimension.
make_broadcastable	Create a decorator that allows a function to be broadcast.
space_broadcastable	Broadcast a 1D function along the 'space' dimension.