Conversion routines (convert)

Functions:

moments_type(values_in, *[, mom_ndim, ...])	Convert between central and raw moments type.
cumulative(values_in, *[, axis, dim, ...])	Convert between moments array and cumulative moments array.
moments_to_comoments(data, *, mom[, ...])	Convert from moments to comoments data.
comoments_to_moments(data, *[, mom_axes, ...])	Convert comoments of same variable to moments array

cmomy.convert.moments_type(values_in, *, mom_ndim=None, mom_axes=None, mom_dims=None, mom_params=None, to='central', out=None, dtype=None, casting='same_kind', order=None, axes_to_end=False, keep_attrs=None, apply_ufunc_kwargs=None)

Convert between central and raw moments type.

Parameters:

• values_in (array-like, DataArray, or Dataset) – The moments array to convert from.

• mom_ndim ({1, 2}, optional) – Value indicates if moments (mom_ndim = 1) or comoments (mom_ndim=2). If not specified and data is an xarray object attempt to infer mom_ndim from mom_dims. Otherwise, default 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 (MomParams or 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 MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

• to ({"raw", "central"}) – The style of the values_in to convert to. If "raw", convert from central to raw. If "central" convert from raw to central moments.

• 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.

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

• casting ({'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional) –

  Controls what kind of data casting may occur.

  • ’no’ means the data types should not be cast at all.

  • ’equiv’ means only byte-order changes are allowed.

  • ’safe’ means only casts which can preserve values are allowed.

  • ’same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.

  • ’unsafe’ (default) means any data conversions may be done.

• order ({"C", "F", "A", "K"}, optional) – Order argument. See numpy.asarray().

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

• 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) – Moments array converted from input_style to opposite format.

Notes

The structure of arrays are as follow. Central moments:

• values_in[..., 0] : weight

• values_in[..., 1] : mean

• values_in[..., k] : kth central moment

Central comoments of variables a and b:

• values_in[..., 0, 0] : weight

• values_in[..., 1, 0] : mean of a

• values_in[....,0, 1] : mean of b

• values_in[..., i, j] : \(\langle (\delta a)^i (\delta b)^j \rangle\),

where a and b are the variables being considered.

Raw moments array:

• values_in[..., 0] : weight

• values_in[..., k] : kth moment \(\langle a^k \rangle\)

Raw comoments array of variables a and b:

• values_in[..., 0, 0] : weight

• values_in[..., i, j] : \(\langle a^i b^j \rangle\),

cmomy.convert.cumulative(values_in, *, axis=MISSING, dim=MISSING, mom_ndim=None, mom_axes=None, mom_dims=None, mom_params=None, inverse=False, out=None, dtype=None, casting='same_kind', order=None, parallel=None, axes_to_end=False, keep_attrs=None, apply_ufunc_kwargs=None)

Convert between moments array and cumulative moments array.

Parameters:

• values_in (array-like, DataArray, or Dataset)

• axis (int) – Axis to reduce/sample along.

• dim (hashable) – Dimension to reduce/sample along.

• mom_ndim ({1, 2}, optional) – Value indicates if moments (mom_ndim = 1) or comoments (mom_ndim=2). If not specified and data is an xarray object attempt to infer mom_ndim from mom_dims. Otherwise, default 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 (MomParams or 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 MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

• inverse (bool, optional) – Default is to create a cumulative moments array. Pass inverse=True to convert from cumulative moments array back to normal moments.

• 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.

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

• casting ({'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional) –

  Controls what kind of data casting may occur.

  • ’no’ means the data types should not be cast at all.

  • ’equiv’ means only byte-order changes are allowed.

  • ’safe’ means only casts which can preserve values are allowed.

  • ’same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.

  • ’unsafe’ (default) means any data conversions may be done.

• order ({"C", "F", "A", "K"}, optional) – Order argument. See numpy.asarray().

• parallel (bool, optional) – If True, use parallel numba numba.njit or numba.guvectorized code if possible. If None, use a heuristic to determine if should attempt to use parallel method.

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

• 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:

out (ndarray or DataArray or Dataset) – Same type as values_in, with moments accumulated over axis.

Examples

>>> import cmomy
>>> x = cmomy.default_rng(0).random((10, 3))
>>> data = cmomy.reduce_vals(x, mom=2, axis=0)
>>> data
array([[10.    ,  0.5248,  0.1106],
       [10.    ,  0.5688,  0.0689],
       [10.    ,  0.5094,  0.1198]])

>>> cdata = cumulative(data, axis=0, mom_ndim=1)
>>> cdata
array([[10.    ,  0.5248,  0.1106],
       [20.    ,  0.5468,  0.0902],
       [30.    ,  0.5344,  0.1004]])

To get the original data back, pass inverse=True

>>> cumulative(cdata, axis=0, mom_ndim=1, inverse=True)
array([[10.    ,  0.5248,  0.1106],
       [10.    ,  0.5688,  0.0689],
       [10.    ,  0.5094,  0.1198]])

cmomy.convert.moments_to_comoments(data, *, mom, mom_axes=None, mom_dims=None, mom_params=None, mom_dims_out=None, dtype=None, order=None, keep_attrs=None, apply_ufunc_kwargs=None)

Convert from moments to comoments data.

Parameters:

• data (array-like or DataArray or Dataset) – Moments array with mom_ndim==1. It is assumed that the last dimension is the moments dimension.

• mom (tuple of int) –

  Moments for comoments array. Pass a negative value for one of the moments to fill all available moments for that dimensions. For example, if original array has moments m (i.e., values.shape=(..., m + 1)), and pass in mom = (2, -1), then this will be transformed to

  mom = (2, m - 2).

• 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 (MomParams or 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 MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

• mom_dims_out (tuple of str) – Moments dimensions for output (mom_ndim=2) data. Defaults to ("mom_0", "mom_1").

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

• order ({"C", "F"}, optional) – Order argument. See numpy.zeros().

• 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) – Co-moments array. Same type as data. Note that new moment dimensions are always the last dimensions.

Examples

>>> import cmomy
>>> x = cmomy.default_rng(0).random(10)
>>> data1 = cmomy.reduce_vals(x, mom=4, axis=0)
>>> data1
array([10.    ,  0.5505,  0.1014, -0.0178,  0.02  ])

>>> moments_to_comoments(data1, mom=(2, -1))
array([[10.    ,  0.5505,  0.1014],
       [ 0.5505,  0.1014, -0.0178],
       [ 0.1014, -0.0178,  0.02  ]])

Note that new moment dimensions are always last.

>>> data = cmomy.default_rng(0).random((6, 1, 2))
>>> a = moments_to_comoments(data, mom_axes=0, mom=(2, -1))
>>> a.shape
(1, 2, 3, 4)
>>> b = moments_to_comoments(np.moveaxis(data, 0, -1), mom=(2, -1))
>>> np.testing.assert_equal(a, b)

Which is identical to

>>> cmomy.reduction.reduce_vals(x, x, mom=(2, 2), axis=0)
array([[10.    ,  0.5505,  0.1014],
       [ 0.5505,  0.1014, -0.0178],
       [ 0.1014, -0.0178,  0.02  ]])

This also works for DataArray data

>>> xdata = xr.DataArray(data1, dims="mom")
>>> xdata
<xarray.DataArray (mom: 5)> Size: 40B
array([10.    ,  0.5505,  0.1014, -0.0178,  0.02  ])
Dimensions without coordinates: mom

>>> moments_to_comoments(xdata, mom=(2, -1))
<xarray.DataArray (mom_0: 3, mom_1: 3)> Size: 72B
array([[10.    ,  0.5505,  0.1014],
       [ 0.5505,  0.1014, -0.0178],
       [ 0.1014, -0.0178,  0.02  ]])
Dimensions without coordinates: mom_0, mom_1

Note that this also works for raw moments.

cmomy.convert.comoments_to_moments(data, *, mom_axes=None, mom_dims=None, mom_params=None, mom_dims_out=None, dtype=None, order=None, keep_attrs=None, apply_ufunc_kwargs=None)

Convert comoments of same variable to moments array

Inverse of moments_to_comoments(). Use with caution. This is intended only to use for symmetric comoment arrays (i.e., one created from comoments_to_moments()).

Parameters:

• data (array-like or DataArray or Dataset) – Moments array with mom_ndim==1. It is assumed that the last dimension is the moments dimension.

• 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_params (MomParams or 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 MomParams object with mom_params=cmomy.MomParams(dims=("a", "b")).

• 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_dims_out (tuple of str) – Moments dimensions for output (mom_ndim=1) data. Defaults to ("mom_0",).

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

• order ({"C", "F"}, optional) – Order argument. See numpy.zeros().

• 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) – Co-moments array. Same type as data. Note that the output moments are in the last dimension.

Examples

>>> import cmomy
>>> x = cmomy.default_rng(0).random(10)
>>> data2 = cmomy.reduce_vals(x, x, mom=(1, 2), axis=0)
>>> data2
array([[10.    ,  0.5505,  0.1014],
       [ 0.5505,  0.1014, -0.0178]])
>>> comoments_to_moments(data2)
array([10.    ,  0.5505,  0.1014, -0.0178])

Note that this is identical to the following:

>>> cmomy.reduce_vals(x, mom=3, axis=0)
array([10.    ,  0.5505,  0.1014, -0.0178])