iqm.cpc.core.dataset.apply_along_coordinate

iqm.cpc.core.dataset.apply_along_coordinate#

iqm.cpc.core.dataset.apply_along_coordinate(data_array: DataArray, coord: str, func: Callable[[ndarray, ndarray], tuple[dict, ndarray]], returns: None = None, add_to: Dataset | None = None, result_parameter: Parameter | None = None, prefix: str = '') → DataArray#
iqm.cpc.core.dataset.apply_along_coordinate(data_array: DataArray, coord: str, func: Callable[[ndarray, ndarray], tuple[dict, ndarray]], returns: Sequence[str], add_to: Dataset | None = None, result_parameter: Parameter | None = None, prefix: str = '') → tuple[DataArray, ...]

Apply a 1-dimensional function along a selected coordinate axis inside a Nd data array.

Computes the result of function func along selected coordinate coord. The function should map a 1d array to a new array of equal size. In addition, it may return a dict of scalars for each function call.

The main use case for this is fitting, where func returns a fit to some raw data, plus the found fit parameters.

For example, if data_array has dimensions A, B, and C, and we apply a fitting function along B, the fitter func function is evaluated for each coordinate tuple spanned by A and C and gets arrays of len(B) as input. The result has the same shape and dimensions as data_array. Optionally, the fit parameters evaluated at each A,C-coordinate tuple can be returned as separate data arrays if specified in returns. These have the shape (len(A), len(C)) and the names are the fit parameters, i.e. keys returned by func.

Example

def my_fitter(x, y):
    # ... fit function f(x; a) to data y ...
    # Let's say a=5 produces the best fit.
    return {"a": 5}, np.random.rand(len(y))

my_data = xarray.DataArray(
    np.random.rand(5, 3),
    dims=["x", "color"],
    coords=[[1, 2, 3, 4, 5], [0, 125, 255]]
)

fit, a = apply_along_coordinate(
    data_array=my_data,
    coord="x",
    func=my_fitter,
    returns=["a"]
)
assert my_data.sizes == fit.sizes == {'x': 5, 'color': 3}
assert a.sizes == {"color": 3}
Parameters:

  • data_array (DataArray) – DataArray that contains the Nd data to operate on.

  • coord (str) – Name of the coordinate over which the 1d operation is performed. Can be any coordinate or dimension of data_array.

  • func (Callable[[ndarray, ndarray], tuple[dict, ndarray]]) – A function that takes 1-dimensional data in format (x, y) and returns a dictionary containing the extra results (e.g. fit parameters), and the computed 1-d array.

  • returns (Sequence[str] | None) – Names of extra results to return. Each string should match one of the keys returned by func. The arrays are added to the result tuple in the same order as given in returns. Note that the computed array is always returned first and does not need to be specified.

  • add_to (Dataset | None) – If given, the returned arrays are added to this dataset. The dataset is modified as a side effect.

  • result_parameter (Parameter | None) – This parameter represents the computed data. By default will be generated by generate_fit_parameter().

  • prefix (str) – If given, the names of all arrays in returns are prefixed with <prefix>_. Used to avoid name clashes with existing data variables.

Returns:

List of data arrays depending on returns. The first array is always the result produced by applying func along the axis coord. It has the same \(N\) dimensions as data_array. The other arrays have \(N-1\) dimensions and represent the extras requested in returns.

Return type:

tuple[DataArray, …] | DataArray

Contents