Base Classes

class cmomy.abstract_central.CentralMomentsABC(data, mom_ndim=1)

Bases: ABC, Generic[T_Array]

Wrapper to calculate central moments.

Base data has the form

\[\begin{split}{\rm data}[..., i, j] = \begin{cases} \text{weight} & i = j = 0 \\ \langle x \rangle & i = 1, j = 0 \\ \langle (x - \langle x \rangle^i) (y - \langle y \rangle^j) \rangle & i + j > 0 \end{cases}\end{split}\]

Parameters:

• data (numpy.ndarray or xarray.DataArray) – Moment collection array

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

Attributes:

data	Accessor to numpy array underlying data.
values	Access underlying central moments array.
shape	self.data.shape.
ndim	self.data.ndim.
dtype	self.data.dtype.
mom_ndim	Length of moments.
mom_shape	Shape of moments part.
mom	Number of moments.
val_shape	Shape of values dimensions.
val_ndim	Number of value dimensions.
val_shape_flat	Shape of values part flattened.
shape_flat	Shape of flattened data.
mom_shape_var	Shape of moment part of variance.
shape_var	Total variance shape.
shape_flat_var	Shape of flat variance.

Methods:

to_values()	Access underlying central moments array.
to_numpy()	Access to numpy array underlying class.
new_like([data, copy, copy_kws, verify, strict])	Create new object like self, with new data.
zeros_like()	Create new empty object like self.
copy(**copy_kws)	Create a new object with copy of data.
weight()	Weight data.
mean()	Mean (first moment).
var()	Variance (second central moment).
std()	Standard deviation.
cmom()	Central moments.
to_raw(*[, weights])	Raw moments accumulation array.
rmom()	Raw moments.
fill([value])	Fill data with value.
zero()	Zero out underlying data.
push_data(data)	Push data object to moments.
push_datas(datas[, axis])	Push and reduce multiple average central moments.
push_val(x[, w, broadcast])	Push single sample to central moments.
push_vals(x[, w, axis, broadcast])	Push multiple samples to central moments.
pipe(func_or_method, *args[, _order, _copy, ...])	Apply func_or_method to underlying data and wrap results in class:cmomy.xCentralMoments object.
resample(indices[, axis, first, verify])	Create a new object sampled from index.
zeros(*[, mom, mom_ndim, val_shape, shape, ...])	Create a new base object.
from_data(data, *[, mom, mom_ndim, ...])	Create new object from data array with additional checks.
from_datas(datas, *[, mom, mom_ndim, ...])	Create object from multiple data arrays.
from_vals(x, mom, *[, w, val_shape, dtype, ...])	Create from observations/values.
from_resample_vals(x, mom, *[, full_output])	Create from resample observations/values.
from_raw(raw, *[, mom, mom_ndim, val_shape, ...])	Create object from raw moment data.
from_raws(raws, *[, mom, mom_ndim, ...])	Create object from multiple raw moment arrays.

property data

Accessor to numpy array underlying data.

By convention data has the following meaning for the moments indexes

• data[…,i=0,j=0], weights

• data[…,i=1,j=0]], if only one moment index is one and all others zero, then this is the average value of the variable with unit index.

• all other cases, the central moments <(x0-<x0>)**i0 * (x1 - <x1>)**i1 * …>

abstract to_values()

Access underlying central moments array.

property values

Access underlying central moments array.

to_numpy()

Access to numpy array underlying class.

property shape

self.data.shape.

property ndim

self.data.ndim.

property dtype

self.data.dtype.

property mom_ndim

Length of moments.

if mom_ndim == 1, then single variable moments if mom_ndim == 2, then co-moments.

property mom_shape

Shape of moments part.

property mom

Number of moments.

property val_shape

Shape of values dimensions.

That is shape less moments dimensions.

property val_ndim

Number of value dimensions.

property val_shape_flat

Shape of values part flattened.

property shape_flat

Shape of flattened data.

property mom_shape_var

Shape of moment part of variance.

property shape_var

Total variance shape.

property shape_flat_var

Shape of flat variance.

abstract new_like(data=None, *, copy=False, copy_kws=None, verify=False, strict=False, **kwargs)

Create new object like self, with new data.

Parameters:

• data (numpy.ndarray or xarray.DataArray) – data for new object

• copy (bool) – If True, copy the data. If False, attempt to use view.

• copy_kws (mapping) – extra arguments to copy

• verify (bool) – If True, make sure data is c-contiguous.

• strict (bool, default False) – If True, verify that data has correct shape

• **kwargs (Any) – Extra keyword arguments. arguments to classmethod from_data()

Returns:

object – New object object with zerod out data.

See also

from_data

zeros_like()

Create new empty object like self.

Returns:

output (object) – Object with same attributes as caller, but with data set to zero.

See also

new_like, from_data

copy(**copy_kws)

Create a new object with copy of data.

Parameters:

**copy_kws (Any) – passed to parameter copy_kws in method new_like()

Returns:

output (object) – Same type as calling class. Object with same attributes as caller, but with new underlying data.

See also

new_like, zeros_like

weight()

Weight data.

mean()

Mean (first moment).

var()

Variance (second central moment).

std()

Standard deviation.

cmom()

Central moments.

Strict central moments of the form

\[\text{cmom[..., n, m]} = \langle (x - \langle x \rangle^n) (y - \langle y \rangle^m) \rangle\]

Returns:

output (ndarray or DataArray)

to_raw(*, weights=None)

Raw moments accumulation array.

\[\begin{split}\text{raw[..., n, m]} = \begin{cases} \text{weight} & n = m = 0 \\ \langle x^n y ^m \rangle & \text{otherwise} \end{cases}\end{split}\]

Returns:

raw (ndarray or DataArray)

See also

from_raw

rmom()

Raw moments.

\[\text{rmom[..., n, m]} = \langle x^n y^m \rangle\]

Returns:

raw_moments (ndarray or DataArray)

See also

to_raw, cmom

fill(value=0)

Fill data with value.

Parameters:

value (scalar) – Value to insert into self.data

Returns:

self (object) – Same type as calling class. Same object as caller with data filled with values

zero()

Zero out underlying data.

Returns:

self (object) – Same type as calling class. Same object with data filled with zeros.

See also

fill

push_data(data)

Push data object to moments.

Parameters:

data (array-like) – Accumulation array of same form as self.data

Returns:

output (object) – Same object with pushed data.

push_datas(datas, axis=None, **kwargs)

Push and reduce multiple average central moments.

Parameters:

• datas (array-like, numpy.ndarray or xarray.DataArray) – Collection of accumulation arrays to push onto self. This should have shape like (nrec,) + self.shape if axis=0, where nrec is the number of data objects to sum.

• axis (int) – Axis to reduce along.

• **kwargs (Any) – Extra keyword arguments.

Returns:

output (object) – Same object with pushed data.

push_val(x, w=None, broadcast=False)

Push single sample to central moments.

Parameters:

• x (array-like or tuple of array-like) – Pass single array x=x0`if accumulating moments. Pass tuple of arrays `(x0, x1) if accumulating comoments. x0.shape == self.val_shape

• w (int, float, array-like, optional) – Weight of each sample. If scalar, broadcast w.shape to x0.shape.

• broadcast (bool, optional) – If True, and x1 present, attempt to broadcast x1.shape to x0.shape

Returns:

output (object) – Same object with pushed data.

Notes

Array x0 should have same shape as self.val_shape.

push_vals(x, w=None, axis=None, broadcast=False, **kwargs)

Push multiple samples to central moments.

Parameters:

• x (array-like or tuple of array-like) – Pass single array x=x0`if accumulating moments. Pass tuple of arrays `(x0, x1) if accumulating comoments. x0.shape less axis should be same as self.val_shape.

• w (int, float, array-like, optional) – Weight of each sample. If scalar, broadcast to x0.shape

• broadcast (bool) – If True, and x=(x0, x1), then perform ‘smart’ broadcasting. In this case, if x1.ndim = 1 and len(x1) == x0.shape[axis], then broadcast x1 to x0.shape.

• axis (int) – Axis to reduce along.

• **kwargs (Any) – Extra keyword arguments.

Returns:

output (object) – Same object with pushed data.

pipe(func_or_method, *args, _order=True, _copy=False, _verify=False, _check_mom=True, _kws=None, **kwargs)

Apply func_or_method to underlying data and wrap results in class:cmomy.xCentralMoments object.

This is useful for calling any not implemented methods on numpy.ndarray or xarray.DataArray data.

Parameters:

• func_or_method (str or callable()) – If callable, then apply values = func_or_method(self.to_values(), *args, **kwargs). If string is passed, then values = getattr(self.to_values(), func_or_method)(*args, **kwargs).

• _order (bool, default True) – If True, reorder the data such that mom_dims are last.

• _copy (bool, default False) – If True, copy the resulting data. Otherwise, try to use a view. This is passed as copy=_copy to from_data().

• _verify (bool, default False) – If True, ensure underlying data is contiguous. Passed as verify=_verify to from_data()

• _check_mom (bool, default True) – If True, check the resulting object has the same moment shape as the current object.

• _kws (Mapping, optional) – Extra arguments to from_data().

• *args (Any) – Extra positional arguments to func_or_method

• **kwargs (Any) – Extra keyword arguments to func_or_method

Returns:

output (cmomy.xCentralMoments) – New cmomy.xCentralMoments object after func_or_method is applies to self.to_values()

Notes

Use leading underscore for _order, _copy to avoid name possible name clashes.

See also

from_data

resample(indices, axis=0, *, first=True, verify=False, **kwargs)

Create a new object sampled from index.

Parameters:

• indices (array of int) – Array of shape (nrep, size). If passed, create freq from indices. See randsamp_freq().

• axis (int) – Axis to reduce along.

• first (bool, default True) – if True, and axis != 0, the move the axis to first position. This makes results similar to resample and reduce If first False, then resampled array can have odd shape

• **kwargs (Any) – Extra keyword arguments.

Returns:

output (object) – Instance of calling class The new object will have shape (nrep, ndat, …) + self.shape[:axis] + self.shape[axis+1:]

See also

from_data

abstract classmethod zeros(*, mom=None, mom_ndim=None, val_shape=None, shape=None, dtype=None, zeros_kws=None, **kwargs)

Create a new base object.

Parameters:

• 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

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

• val_shape (tuple) – Shape of values part of data. That is, the non-moment dimensions.

• shape (tuple) – Total shape. shape = val_shape + tuple(m+1 for m in mom)

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

• zeros_kws (mapping) – Optional parameters to numpy.zeros()

• **kwargs (Any) – extra arguments to from_data()

Returns:

output (object) – New instance with zero values.

Notes

The resulting total shape of data is shape + (mom + 1). Must specify either mom or mom_ndim

See also

from_data, numpy.zeros

abstract classmethod from_data(data, *, mom=None, mom_ndim=None, val_shape=None, copy=True, copy_kws=None, verify=False, dtype=None)

Create new object from data array with additional checks.

Parameters:

• data (array-like) – central moments accumulation array.

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

• 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

• val_shape (tuple) – Shape of values part of data. That is, the non-moment dimensions.

• copy (bool) – If True, copy the data. If False, attempt to use view.

• copy_kws (mapping) – extra arguments to copy

• verify (bool) – If True, make sure data is c-contiguous.

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

Returns:

out (object) – Same type as calling class.

abstract classmethod from_datas(datas, *, mom=None, mom_ndim=None, val_shape=None, dtype=None, verify=False, axis=0, **kwargs)

Create object from multiple data arrays.

Parameters:

• datas (ndarray) – Array of multiple Moment arrays. datas[…, i, …] is the ith data array, where i is in position axis.

• 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

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

• val_shape (tuple) – Shape of values part of data. That is, the non-moment dimensions.

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

• verify (bool) – If True, make sure data is c-contiguous.

• axis (int) – Axis to reduce along.

• **kwargs (Any) – Extra arguments.

Returns:

output (object)

See also

from_data

abstract classmethod from_vals(x, mom, *, w=None, val_shape=None, dtype=None, broadcast=False, axis=0, **kwargs)

Create from observations/values.

Parameters:

• x (array-like or tuple of array-like) – For moments, pass single array-like objects x=x0. For comoments, pass tuple of array-like objects x=(x0, x1).

• w (scalar or array-like, optional) – Optional weights. If scalar or array, attempt to broadcast to x0.shape

• axis (int) – Axis to reduce along.

• 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

• val_shape (tuple) – Shape of values part of data. That is, the non-moment dimensions.

• broadcast (bool) – If True, and x=(x0, x1), then perform ‘smart’ broadcasting. In this case, if x1.ndim = 1 and len(x1) == x0.shape[axis], then broadcast x1 to x0.shape.

• **kwargs (Any) – Extra keyword arguments.

Returns:

output (object)

See also

push_vals

abstract classmethod from_resample_vals(x, mom, *, full_output=False, **kwargs)

Create from resample observations/values.

This effectively resamples x.

Parameters:

• x (array-like or tuple of array-like) – For moments, pass single array-like objects x=x0. For comoments, pass tuple of array-like objects x=(x0, x1).

• 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

• full_output (bool) – If True, also return freq array

• nrep (int) – Number of resample replicates.

• nsamp (int) – Number of samples in a single resampled replicate. Defaults to size of data along sampled axis.

• freq (array of int) – Array of shape (nrep, size) where nrep is the number of replicates and size = self.shape[axis]. freq is the weight that each sample contributes to resamples values. See randsamp_freq()

• indices (array of int) – Array of shape (nrep, size). If passed, create freq from indices. See randsamp_freq().

• w (scalar or array-like, optional) – Optional weights. If scalar or array, attempt to broadcast to x0.shape

• axis (int) – Axis to reduce along.

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

• broadcast (bool) – If True, and x=(x0, x1), then perform ‘smart’ broadcasting. In this case, if x1.ndim = 1 and len(x1) == x0.shape[axis], then broadcast x1 to x0.shape.

• parallel (bool, default True) – If True, perform resampling in parallel.

• resample_kws (mapping) – Extra arguments to resample_vals()

• rng (Generator) – Random number generator object. Defaults to output of default_rng().

• **kwargs (Any) – Extra arguments to CentralMoments.from_data

Returns:

• out (object) – Instance of calling class

• freq (ndarray, optional) – If full_output is True, also return freq array

See also

cmomy.resample.resample_vals, cmomy.resample.randsamp_freq, cmomy.resample.freq_to_indices, cmomy.resample.indices_to_freq

abstract classmethod from_raw(raw, *, mom=None, mom_ndim=None, val_shape=None, dtype=None, convert_kws=None, **kwargs)

Create object from raw moment data.

raw[…, i, j] = <x**i y**j>. raw[…, 0, 0] = weight

Parameters:

• raw (ndarray) – Raw moment array.

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

• 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

• val_shape (tuple) – Shape of values part of data. That is, the non-moment dimensions.

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

• convert_kws (mapping) – Extra arguments to to_central_moments() or to_central_comoments()

• **kwargs (Any) – Extra arguments to from_data()

Returns:

output (object)

See also

to_raw, rmom, to_central_moments, to_central_comoments

Notes

Weights are taken from raw[...,0, 0]. Using raw moments can result in numerical issues, especially for higher moments. Use with care.

abstract classmethod from_raws(raws, *, mom=None, mom_ndim=None, val_shape=None, axis=0, dtype=None, convert_kws=None, **kwargs)

Create object from multiple raw moment arrays.

Parameters:

• raws (ndarray) – raws[…,i,…] is the ith sample of a raw array, Note that raw[…,i,j] = <x0**i, x1**j> where i is in position axis

• axis (int) – Axis to reduce along.

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

• 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

• val_shape (tuple) – Shape of values part of data. That is, the non-moment dimensions.

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

• convert_kws (mapping) – Extra arguments to to_central_moments() or to_central_comoments()

• **kwargs (Any) – Extra arguments to from_datas()

Returns:

output (object)

See also

from_raw, from_datas

to_central_moments

convert raw to central moments

to_central_comoments

convert raw to central comoments

Notes

Weights are taken from raw[...,0, 0]. Using raw moments can result in numerical issues, especially for higher moments. Use with care.