Interface to utility functions (cmomy.utils)

Interface to utility functions (cmomy.utils)#

Functions:

moveaxis_order(x[, axis, dest, dim, ...])

Get new integer order for transpose corresponding to moveaxis parameters.

moveaxis(x[, axis, dest, dim, dest_dim, ...])

Generalized moveaxis for moments arrays.

moment_indexer(name, mom_ndim[, squeeze])

Get indexer for moments

select_moment(data, name, *[, mom_ndim, ...])

Select specific moments for a central moments array.

assign_moment(data[, moment, mom_ndim, ...])

Update weights of moments array.

vals_to_data(x, *y, mom[, weight, mom_dims, ...])

Convert values to central moments array.
cmomy.utils.moveaxis_order(x, axis=MISSING, dest=MISSING, *, dim=MISSING, dest_dim=MISSING, mom_ndim=None, mom_axes=None, mom_dims=None, mom_params=None, axes_to_end=False, allow_select_mom_axes=False)[source]#

Get new integer order for transpose corresponding to moveaxis parameters.

cmomy.utils.moveaxis(x, axis=MISSING, dest=MISSING, *, dim=MISSING, dest_dim=MISSING, mom_ndim=None, mom_axes=None, mom_dims=None, mom_params=None, axes_to_end=False, allow_select_mom_axes=False)[source]#

Generalized moveaxis for moments arrays.

Parameters:

  • x (ndarray or DataArray) – input data

  • axis (complex or sequence of complex) – Original positions of axes to move. Complex values wrapped relative to mom_ndim.

  • dest (complex or sequence of complex) – Destination positions for each original axes.

  • dim (str or sequence of hashable) – Original dimensions to move (for DataArray).

  • dest_dim (str or sequence of hashable) – Destination of each original dimension.

  • mom_ndim ({1, 2}, optional) – If mom_ndim is not None, then wrap axis relative to mom_ndim. For Example, with mom_ndim=``2``, axis = -1 will be transformed to axis = -3. If mom_dims is passed and data is an xarray object, infer mom_n=ndim from mom_dims.

  • mom_axes (int or tuple of int, optional) – Location of the moment dimensions. Default to (-mom_ndim, -mom_ndim+1, ...). If specified and mom_ndim is None, set mom_ndim to len(mom_axes). Note that if mom_axes is specified, negative values are relative to the end of the array. This is also the case for axes if mom_axes is specified.

  • mom_dims (hashable or tuple of hashable) – Name of moment dimensions. If specified, infer mom_ndim from mom_dims. If also pass mom_ndim, check that mom_dims is consistent with mom_dims. If not specified, defaults to data.dims[-mom_ndim:]. This is primarily used if data is a Dataset, or if mom_dims are not the last dimensions.

  • mom_params (cmomy.MomParams or cmomy.MomParamsDict or dict, optional) – Moment parameters. You can set moment parameters axes and dims using this option. For example, passing mom_params={"dim": ("a", "b")} is equivalent to passing mom_dims=("a", "b"). You can also pass as a cmomy.MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

  • axes_to_end (bool) – If True, place sampled dimension (if exists in output) and moment dimensions at end of output. Otherwise, place sampled dimension (if exists in output) at same position as input axis and moment dimensions at same position as input (if input does not contain moment dimensions, place them at end of array).

  • allow_select_mom_axes (bool, default False) – If True, allow moving moment axes. Otherwise, raise ValueError if try to move mom_axes.

Returns:

out (ndarray or DataArray) – Same type as x with moved axis.

Notes

Must specify either axis or dim and either dest or dest_dim.

See also

numpy.moveaxis

Examples

>>> x = np.zeros((2, 3, 4, 5))
>>> moveaxis(x, 0, -1).shape
(3, 4, 5, 2)

Specifying mom_ndim will result in negative complex axis relative to the moments dimensions.

>>> moveaxis(x, 0, -1j, mom_ndim=1).shape
(3, 4, 2, 5)

Note that if mom_ndim is not specified, then complex axis are equivalent to integer axis.

>>> moveaxis(x, 0, -1j).shape
(3, 4, 5, 2)

Multiple axes can also be specified.

>>> moveaxis(x, (1, 0), (-2j, -1j), mom_ndim=1).shape
(4, 3, 2, 5)

This also works with dataarrays

>>> dx = xr.DataArray(x, dims=["a", "b", "c", "mom_0"])
>>> moveaxis(dx, dim="a", dest=-1j, mom_ndim=1).dims
('b', 'c', 'a', 'mom_0')

All the routines in cmomy accept moment dimensions in arbitrary locations. However, it is often easiest to work with these dimensions as the last dimensions in an array. You can easily achieve this with moveaxis with the parameter axes_to_end=True. For example:

>>> moveaxis(x, mom_axes=(0, 1), axes_to_end=True).shape
(4, 5, 2, 3)

>>> moveaxis(x, axis=-1, mom_axes=(1, 2), axes_to_end=True).shape
(2, 5, 3, 4)

>>> moveaxis(x, axis=-2j, mom_ndim=2, axes_to_end=True).shape
(3, 2, 4, 5)
cmomy.utils.moment_indexer(name, mom_ndim, squeeze=True)[source]#

Get indexer for moments

Parameters:

  • moment ({"weight", "ave", "var", "cov", "xave", "xvar", "yave", "yvar", "xmom_0", "xmom_1", "ymom_0", "ymom_1"}) –

    Name of moment(s) to select.

    • "weight" : weights

    • "ave" : Averages.

    • "var": Variance.

    • "cov": Covariance if mom_ndim == 2, or variace if mom_ndim == 1.

    • "xave": Average of first variable.

    • "xvar": Variance of first variable.

    • "yave": Average of second variable (if mom_ndim == 2).

    • "yvar": Variace of second variable (if mom_ndim == 2).

    • "all": All values.

    Names "weight", "xave", "yave", "xvar", "yvar", "cov" imply shape data.shape[:-mom_ndim]. Names "ave", "var" imply shape (*data.shape[:-mom_ndim], mom_ndim), unless mom_ndim == 1 and squeeze = True.

  • mom_ndim ({1, 2}) – Value indicates if moments (mom_ndim = 1) or comoments (mom_ndim=2). Defaults to mom_ndim=1.

  • squeeze (bool, default False) – If True, squeeze last dimension if name is one of ave or var and mom_ndim == 1.

Returns:

indexer (tuple)

cmomy.utils.select_moment(data, name, *, mom_ndim=None, mom_axes=None, mom_dims=None, mom_params=None, squeeze=True, dim_combined='variable', coords_combined=None, keep_attrs=None, apply_ufunc_kwargs=None)[source]#

Select specific moments for a central moments array.

Parameters:

  • data (DataArray or ndarray) – Moment collection array

  • mom_ndim ({1, 2}) – Value indicates if moments (mom_ndim = 1) or comoments (mom_ndim=2). Defaults to mom_ndim=1.

  • mom_axes (int or tuple of int, optional) – Location of the moment dimensions. Default to (-mom_ndim, -mom_ndim+1, ...). If specified and mom_ndim is None, set mom_ndim to len(mom_axes). Note that if mom_axes is specified, negative values are relative to the end of the array. This is also the case for axes if mom_axes is specified.

  • mom_dims (hashable or tuple of hashable) – Name of moment dimensions. If specified, infer mom_ndim from mom_dims. If also pass mom_ndim, check that mom_dims is consistent with mom_dims. If not specified, defaults to data.dims[-mom_ndim:]. This is primarily used if data is a Dataset, or if mom_dims are not the last dimensions.

  • mom_params (cmomy.MomParams or cmomy.MomParamsDict or dict, optional) – Moment parameters. You can set moment parameters axes and dims using this option. For example, passing mom_params={"dim": ("a", "b")} is equivalent to passing mom_dims=("a", "b"). You can also pass as a cmomy.MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

  • moment ({"weight", "ave", "var", "cov", "xave", "xvar", "yave", "yvar", "xmom_0", "xmom_1", "ymom_0", "ymom_1"}) –

    Name of moment(s) to select.

    • "weight" : weights

    • "ave" : Averages.

    • "var": Variance.

    • "cov": Covariance if mom_ndim == 2, or variace if mom_ndim == 1.

    • "xave": Average of first variable.

    • "xvar": Variance of first variable.

    • "yave": Average of second variable (if mom_ndim == 2).

    • "yvar": Variace of second variable (if mom_ndim == 2).

    • "all": All values.

    Names "weight", "xave", "yave", "xvar", "yvar", "cov" imply shape data.shape[:-mom_ndim]. Names "ave", "var" imply shape (*data.shape[:-mom_ndim], mom_ndim), unless mom_ndim == 1 and squeeze = True.

  • squeeze (bool, default False) – If True, squeeze last dimension if name is one of ave or var and mom_ndim == 1.

  • dim_combined (str, optional) – Name of dimension for options that produce multiple values (e.g., name="ave").

  • coords_combined (str or sequence of str, optional) – Coordates to assign to dim_combined. Defaults to names of moments dimension(s)

  • keep_attrs ({"drop", "identical", "no_conflicts", "drop_conflicts", "override"} or bool, optional) –

    • ‘drop’ or False: empty attrs on returned xarray object.

    • ’identical’: all attrs must be the same on every object.

    • ’no_conflicts’: attrs from all objects are combined, any that have the same name must also have the same value.

    • ’drop_conflicts’: attrs from all objects are combined, any that have the same name but different values are dropped.

    • ’override’ or True: skip comparing and copy attrs from the first object to the result.

  • apply_ufunc_kwargs (dict-like) – Extra parameters to xarray.apply_ufunc(). One useful option is on_missing_core_dim, which can take the value "copy" (the default), "raise", or "drop" and controls what to do with variables of a Dataset missing core dimensions. Other options are join, dataset_join, dataset_fill_value, and dask_gufunc_kwargs. Unlisted options are handled internally.

Returns:

output (ndarray or DataArray or Dataset) – Same type as data. If name is ave or var, the last dimensions of output has shape mom_ndim with each element corresponding to the ith variable. If squeeze=True and mom_ndim==1, this last dimension is removed. For all other name options, output has shape of input with moment dimensions removed. In all cases, mom_dims or mom_axes are first moved to the last dimensions.

Examples

>>> data = np.arange(2 * 3).reshape(2, 3)
>>> data
array([[0, 1, 2],
       [3, 4, 5]])
>>> select_moment(data, "weight", mom_ndim=1)
array([0, 3])
>>> select_moment(data, "ave", mom_ndim=1)
array([1, 4])

Note that with squeeze = False ``, selecting ``ave and var will result in the last dimension having size mom_ndim. If squeeze = True (the default) and mom_ndim==1, this dimension will be removed

>>> select_moment(data, "ave", mom_ndim=1, squeeze=False)
array([[1],
       [4]])

>>> select_moment(data, "xave", mom_ndim=2)
array(3)
>>> select_moment(data, "cov", mom_ndim=2)
array(4)

Use options "xmom_0", to select all values with first moment equal 0, etc

>>> select_moment(data, "xmom_0", mom_ndim=2)
array([0, 1, 2])
>>> select_moment(data, "ymom_1", mom_ndim=2)
array([1, 4])
cmomy.utils.assign_moment(data, moment=None, *, mom_ndim=None, mom_axes=None, mom_dims=None, mom_params=None, squeeze=True, copy=True, dim_combined=None, keep_attrs=None, apply_ufunc_kwargs=None, **moment_kwargs)[source]#

Update weights of moments array.

Parameters:

  • data (ndarray or DataArray) – Moments array.

  • moment (mapping of str to array-like) –

    Mapping from moment name to new value. Allowed moment names are:

    • "weight" : weights

    • "ave" : Averages.

    • "var": Variance.

    • "cov": Covariance if mom_ndim == 2, or variace if mom_ndim == 1.

    • "xave": Average of first variable.

    • "xvar": Variance of first variable.

    • "yave": Average of second variable (if mom_ndim == 2).

    • "yvar": Variace of second variable (if mom_ndim == 2).

    • "xmom_n", "ymom_n": All values with first (second) variable moment == n.

    • "all": All values.

    Names "weight", "xave", "yave", "xvar", "yvar", "cov" imply shape data.shape[:-mom_ndim]. Names "ave", "var" imply shape (*data.shape[:-mom_ndim], mom_ndim), unless mom_ndim == 1 and squeeze = True.

  • mom_ndim ({1, 2}) – Value indicates if moments (mom_ndim = 1) or comoments (mom_ndim=2). Defaults to mom_ndim=1.

  • mom_axes (int or tuple of int, optional) – Location of the moment dimensions. Default to (-mom_ndim, -mom_ndim+1, ...). If specified and mom_ndim is None, set mom_ndim to len(mom_axes). Note that if mom_axes is specified, negative values are relative to the end of the array. This is also the case for axes if mom_axes is specified.

  • mom_dims (hashable or tuple of hashable) – Name of moment dimensions. If specified, infer mom_ndim from mom_dims. If also pass mom_ndim, check that mom_dims is consistent with mom_dims. If not specified, defaults to data.dims[-mom_ndim:]. This is primarily used if data is a Dataset, or if mom_dims are not the last dimensions.

  • mom_params (cmomy.MomParams or cmomy.MomParamsDict or dict, optional) – Moment parameters. You can set moment parameters axes and dims using this option. For example, passing mom_params={"dim": ("a", "b")} is equivalent to passing mom_dims=("a", "b"). You can also pass as a cmomy.MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

  • squeeze (bool, default False) – If True, squeeze last dimension if name is one of ave or var and mom_ndim == 1.

  • copy (bool, default True) – If True (the default), return new array with updated weights. Otherwise, return the original array with weights updated inplace. Note that a copy is always created for a dask backed object.

  • dim_combined (str, optional) – Name of dimensions for multiple values. Must supply if passing in multiple values for name="ave" etc.

  • keep_attrs ({"drop", "identical", "no_conflicts", "drop_conflicts", "override"} or bool, optional) –

    • ‘drop’ or False: empty attrs on returned xarray object.

    • ’identical’: all attrs must be the same on every object.

    • ’no_conflicts’: attrs from all objects are combined, any that have the same name must also have the same value.

    • ’drop_conflicts’: attrs from all objects are combined, any that have the same name but different values are dropped.

    • ’override’ or True: skip comparing and copy attrs from the first object to the result.

  • apply_ufunc_kwargs (dict-like) – Extra parameters to xarray.apply_ufunc(). One useful option is on_missing_core_dim, which can take the value "copy" (the default), "raise", or "drop" and controls what to do with variables of a Dataset missing core dimensions. Other options are join, dataset_join, dataset_fill_value, and dask_gufunc_kwargs. Unlisted options are handled internally.

  • **moment_kwargs (ArrayLike | xr.DataArray | xr.Dataset) – Keyword argument form of moment. Must provide either moment or moment_kwargs.

Returns:

output (ndarray or DataArray) – Same type as data with moment name updated to value.

See also

select_moment

Examples

>>> data = np.arange(3)
>>> data
array([0, 1, 2])

>>> assign_moment(data, weight=-1, mom_ndim=1)
array([-1,  1,  2])

>>> assign_moment(data, ave=-1, mom_ndim=1)
array([ 0, -1,  2])

>>> assign_moment(data, var=-1, mom_ndim=1)
array([ 0,  1, -1])

Note that you can chain these together. Note that the order of evaluation is the order values are passed.

>>> assign_moment(data, weight=-1, ave=-2, mom_ndim=1)
array([-1, -2,  2])

For multidimensional data, the passed value must conform to the selected data

>>> data = np.arange(2 * 3).reshape(2, 3)

Selecting ave for this data with mom_ndim=1 and squeeze=False would have shape (2, 1).

>>> assign_moment(data, ave=np.ones((2, 1)), mom_ndim=1, squeeze=False)
array([[0, 1, 2],
       [3, 1, 5]])

The squeeze parameter has the same meaning as for select_moment()

>>> assign_moment(data, ave=np.ones(2), mom_ndim=1, squeeze=True)
array([[0, 1, 2],
       [3, 1, 5]])
cmomy.utils.vals_to_data(x, *y, mom, weight=None, mom_dims=None, mom_params=None, dtype=None, out=None, keep_attrs=None, apply_ufunc_kwargs=None)[source]#

Convert values to central moments array.

This allows passing values based observations to data routines. See examples below for more details

Parameters:

  • x (array-like or DataArray) – First value.

  • *y (array-like or DataArray) – Secondary value (if comoments).

  • mom (int or tuple of int) – Order or moments. If integer or length one tuple, then moments are for a single variable. If length 2 tuple, then comoments of two variables

  • weight (array-like, optional) – Optional weights. Can be scalar, 1d array of length args[0].shape[axis] or array of same form as args[0].

  • mom_dims (hashable or tuple of hashable) – Name of moment dimensions. Defaults to ("mom_0",) for mom_ndim==1 and (mom_0, mom_1) for mom_ndim==2

  • mom_params (cmomy.MomParams or cmomy.MomParamsDict or dict, optional) – Moment parameters. You can set moment parameters axes and dims using this option. For example, passing mom_params={"dim": ("a", "b")} is equivalent to passing mom_dims=("a", "b"). You can also pass as a cmomy.MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

  • dtype (dtype) – Optional dtype for output data.

  • out (ndarray) – Optional output array. If specified, output will be a reference to this array. Note that if the output if method returns a Dataset, then this option is ignored.

  • keep_attrs ({"drop", "identical", "no_conflicts", "drop_conflicts", "override"} or bool, optional) –

    • ‘drop’ or False: empty attrs on returned xarray object.

    • ’identical’: all attrs must be the same on every object.

    • ’no_conflicts’: attrs from all objects are combined, any that have the same name must also have the same value.

    • ’drop_conflicts’: attrs from all objects are combined, any that have the same name but different values are dropped.

    • ’override’ or True: skip comparing and copy attrs from the first object to the result.

  • apply_ufunc_kwargs (dict-like) – Extra parameters to xarray.apply_ufunc(). One useful option is on_missing_core_dim, which can take the value "copy" (the default), "raise", or "drop" and controls what to do with variables of a Dataset missing core dimensions. Other options are join, dataset_join, dataset_fill_value, and dask_gufunc_kwargs. Unlisted options are handled internally.

Returns:

data (ndarray or DataArray)

Notes

Values x, y and weight must be broadcastable.

Note that if input data is a chunked dask array, then out is ignored, and a new array is always created.

Also, broadcasting is different here then reduce_vals(), resample_vals(), etc. For these reduction functions, you can, for example, pass a 1-D` array for y with N-D x regardless if the axis is not the last axis. This is because those reduction functions have a axis parameter that can be used to infer the intended shape of y (and weight). In this function, you have to specify y and weight such that they broadcast to x.

Examples

>>> w = np.full((2), 0.1)
>>> x = np.full((1, 2), 0.2)
>>> out = vals_to_data(x, weight=w, mom=2)
>>> out.shape
(1, 2, 3)
>>> print(out[..., 0])
[[0.1 0.1]]
>>> print(out[..., 1])
[[0.2 0.2]]
>>> y = np.full((2, 1, 2), 0.3)
>>> out = vals_to_data(x, y, weight=w, mom=(2, 2))
>>> out.shape
(2, 1, 2, 3, 3)
>>> print(out[..., 0, 0])
[[[0.1 0.1]]

 [[0.1 0.1]]]
>>> print(out[..., 1, 0])
[[[0.2 0.2]]

 [[0.2 0.2]]]
>>> print(out[..., 0, 1])
[[[0.3 0.3]]

 [[0.3 0.3]]]