cmomy.CentralMomentsArray

Contents

cmomy.CentralMomentsArray#

class cmomy.CentralMomentsArray(obj, *, mom_ndim=None, mom_axes=None, copy=None, dtype=None, order=None, mom_params=None, fastpath=False)[source]#

Bases: CentralMomentsABC[ndarray[Any, dtype[FloatT]], MomParamsArray], Generic[FloatT]

Central moments wrapper of ndarray arrays.

Parameters:

  • obj (numpy.ndarray) – Central moments array.

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

  • copy (bool, optional) – If True, copy the data. If None or False, attempt to use view. Note that False values will be converted to None for numpy versions >2.0. This will be changed to reflect the new behavior of the copy parameter to numpy.array() when the minimum numpy version >2.0.

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

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

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

  • fastpath (bool) – For internal use.

See also

cmomy.wrap, cmomy.wrap_reduce_vals, cmomy.wrap_resample_vals, cmomy.wrap_raw

Notes

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}\]

Methods

assign_moment([moment, squeeze, copy, ...])

Create object with update weight, average, etc.

astype(dtype, *[, order, casting, subok, copy])

Underlying data cast to specified type

cmom()

Central moments.

copy()

Create a new object with copy of data.

cov()

Covariance (or variance if mom_ndim==1).

cumulative(*[, axis, axes_to_end, out, ...])

Convert to cumulative moments.

fill([value])

Fill data with value.

jackknife_and_reduce(*[, data_reduced, ...])

Jackknife resample and reduce

mean([squeeze])

Mean (first moment).

moments_to_comoments(*, mom[, dtype, order])

Convert moments (mom_ndim=1) to comoments (mom_ndim=2).

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

Generalized moveaxis

new_like([obj, verify, copy, dtype, order, ...])

Create new object like self, with new data.

pipe(func_or_method, *args[, _reorder, ...])

Apply func_or_method to underlying data and wrap results in new wrapped object.

push_data(data, *[, casting, parallel, scale])

Push data object to moments.

push_datas(datas, *[, axis, mom_axes, ...])

Push and reduce multiple average central moments.

push_val(x, *y[, weight, casting, parallel])

Push single sample to central moments.

push_vals(x, *y[, axis, weight, casting, ...])

Push multiple samples to central moments.

reduce([axis, by, block, axes_to_end, out, ...])

Create new object reduce along axis.

resample(indices, *[, axis, last])

Create a new object sampled from index.

resample_and_reduce(*[, axis, axes_to_end, ...])

Bootstrap resample and reduce.

reshape(shape, *[, order])

Create a new object with reshaped data.

rmom()

Raw moments.

select_moment(name, *[, squeeze, ...])

Select specific moments.

std([squeeze])

Standard deviation (ddof=0).

to_dataarray(*[, dims, attrs, coords, name, ...])

Create a CentralMomentsData object from self.

to_numpy()

Coerce wrapped data to ndarray if possible.

to_raw(*[, weight])

Raw moments accumulation array.

to_x(*[, dims, attrs, coords, name, ...])

Alias to to_dataarray()

var([squeeze])

Variance (second central moment).

weight()

Weight data.

zero()

Zero out underlying data.

zeros(*, mom[, val_shape, dtype, order])

Create a new base object.

zeros_like()

Create new empty object like self.

Attributes

dtype

DType of wrapped object.

mom

Moments tuple.

mom_axes

mom_ndim

Number of moment dimensions.

mom_params

Moments parameters object.

mom_shape

Shape of moments dimensions.

ndim

Total number of dimensions.

obj

Underlying object.

shape

Shape of wrapped object.

val_ndim

Number of values dimensions (ndim - mom_ndim).

val_shape

Shape of values dimensions.

Dunder Methods

__add__(other)

Add objects to new object.

__getitem__(key)

Get new object by indexing.

__iadd__(other)

Self adder.

__imul__(scale)

Inplace multiply.

__isub__(other)

Inplace subtraction.

__mul__(scale)

New object with weight scaled by scale.

__sub__(other)

Subtract objects.
property dtype#

DType of wrapped object.

__getitem__(key)[source]#

Get new object by indexing.

Note that only objects with the same moment(s) shape are allowed.

If you want to extract data in general, use self.to_values()[….].

to_numpy()[source]#

Coerce wrapped data to ndarray if possible.

new_like(obj=None, *, verify=False, copy=None, dtype=None, order=None, fastpath=False)[source]#

Create new object like self, with new data.

Parameters:

  • obj (numpy.ndarray) – Data for new object. Must be conformable to self.obj.

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

  • copy (bool, optional) – If True, copy the data. If None or False, attempt to use view. Note that False values will be converted to None for numpy versions >2.0. This will be changed to reflect the new behavior of the copy parameter to numpy.array() when the minimum numpy version >2.0.

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

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

  • fastpath (bool) – Internal variable.

Returns:

CentralMomentsArray – New CentralMomentsArray object with zerod out data.

Examples

>>> import cmomy
>>> rng = cmomy.default_rng(0)
>>> da = CentralMomentsArray(rng.random(4))
>>> da
<CentralMomentsArray(mom_ndim=1)>
array([0.637 , 0.2698, 0.041 , 0.0165])

>>> da2 = da.new_like()
>>> da2
<CentralMomentsArray(mom_ndim=1)>
array([0., 0., 0., 0.])

>>> da.new_like([1, 2, 3, 4], dtype=np.float32)
<CentralMomentsArray(mom_ndim=1)>
array([1., 2., 3., 4.], dtype=float32)
astype(dtype, *, order=None, casting=None, subok=None, copy=False)[source]#

Underlying data cast to specified type

Parameters:

  • dtype (str or dtype) – Typecode of data-type to cast the array data. Note that a value of None will upcast to np.float64. This is the same behaviour as asarray().

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

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

  • subok (bool, optional) – If True, then sub-classes will be passed-through, otherwise the returned array will be forced to be a base-class array.

  • copy (bool, optional) – By default, astype always returns a newly allocated array. If this is set to False and the dtype requirement is satisfied, the input array is returned insteadof a copy.

Notes

Only numpy.float32 and numpy.float64 dtypes are supported.

See also

numpy.ndarray.astype

push_data(data, *, casting='same_kind', parallel=False, scale=None)[source]#

Push data object to moments.

Parameters:

  • data (array-like or numpy.ndarray) – Accumulation array conformable to self.obj.

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

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

  • scale (array-like) – Scaling to apply to weights of data. Optional.

Returns:

output (CentralMomentsArray) – Same object with pushed data.

Examples

>>> import cmomy
>>> rng = cmomy.default_rng(0)
>>> xs = rng.random((2, 10))
>>> datas = [cmomy.reduce_vals(x, mom=2, axis=0) for x in xs]
>>> da = CentralMomentsArray(datas[0], mom_ndim=1)
>>> da
<CentralMomentsArray(mom_ndim=1)>
array([10.    ,  0.5505,  0.1014])

>>> da.push_data(datas[1])
<CentralMomentsArray(mom_ndim=1)>
array([20.    ,  0.5124,  0.1033])

Which is equivalent to

>>> cmomy.wrap_reduce_vals(xs.reshape(-1), mom=2, axis=0)
<CentralMomentsArray(mom_ndim=1)>
array([20.    ,  0.5124,  0.1033])
push_datas(datas, *, axis=-1, mom_axes=None, casting='same_kind', parallel=None)[source]#

Push and reduce multiple average central moments.

Parameters:

  • datas (array-like or numpy.ndarray) – Collection of accumulation arrays to push onto self.

  • axis (int, optional) – Axis to reduce/sample along. Note that negative values are relative to data.ndim - mom_ndim. It is assumed that the last dimensions are for moments. For example, if data.shape == (1,2,3) with mom_ndim=1, axis = -1 `` would be equivalent to ``axis = 1. Defaults to axis=-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.

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

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

Returns:

output (CentralMomentsArray) – Same object with pushed data.

Examples

>>> import cmomy
>>> rng = cmomy.default_rng(0)
>>> xs = rng.random((2, 10))
>>> datas = cmomy.reduce_vals(xs, axis=1, mom=2)
>>> da = CentralMomentsArray.zeros(mom=2)
>>> da.push_datas(datas, axis=0)
<CentralMomentsArray(mom_ndim=1)>
array([20.    ,  0.5124,  0.1033])

Which is equivalent to

>>> cmomy.wrap_reduce_vals(xs.reshape(-1), mom=2, axis=0)
<CentralMomentsArray(mom_ndim=1)>
array([20.    ,  0.5124,  0.1033])
push_val(x, *y, weight=None, casting='same_kind', parallel=False)[source]#

Push single sample to central moments.

Parameters:

  • x (array-like or numpy.ndarray) – Values to push onto self.

  • *y (array-like or numpy.ndarray) – Additional values (needed if mom_ndim > 1)

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

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

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

Returns:

output (CentralMomentsArray) – Same object with pushed data.

Notes

Array x0 should have same shape as self.val_shape.

Examples

>>> import cmomy
>>> rng = cmomy.default_rng(0)
>>> x = rng.random((10, 2))
>>> y = rng.random(10)
>>> w = rng.random(10)

>>> da = CentralMomentsArray.zeros(val_shape=(2,), mom=(2, 2))
>>> for xx, yy, ww in zip(x, y, w):
...     _ = da.push_val(xx, yy, weight=ww)

>>> da
<CentralMomentsArray(mom_ndim=2)>
array([[[ 5.4367e+00,  6.0656e-01,  9.9896e-02],
        [ 6.4741e-01,  3.3791e-02, -5.1117e-03],
        [ 5.0888e-02, -1.0060e-02,  7.0290e-03]],

       [[ 5.4367e+00,  6.0656e-01,  9.9896e-02],
        [ 3.9793e-01,  6.3224e-03, -2.2669e-02],
        [ 9.3979e-02,  9.9433e-04,  6.5765e-03]]])

Which is the same as

>>> cmomy.wrap_reduce_vals(x, y, weight=w, mom=(2, 2), axis=0)
<CentralMomentsArray(mom_ndim=2)>
array([[[ 5.4367e+00,  6.0656e-01,  9.9896e-02],
        [ 6.4741e-01,  3.3791e-02, -5.1117e-03],
        [ 5.0888e-02, -1.0060e-02,  7.0290e-03]],

       [[ 5.4367e+00,  6.0656e-01,  9.9896e-02],
        [ 3.9793e-01,  6.3224e-03, -2.2669e-02],
        [ 9.3979e-02,  9.9433e-04,  6.5765e-03]]])
push_vals(x, *y, axis=-1, weight=None, casting='same_kind', parallel=None)[source]#

Push multiple samples to central moments.

Parameters:

  • x (array) – Value to reduce.

  • *y (array-like) – Additional array (if self.mom_ndim == 2).

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

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

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

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

Returns:

output (CentralMomentsArray) – Same object with pushed data.

Examples

>>> import cmomy
>>> rng = cmomy.default_rng(0)
>>> x = rng.random((10, 2))
>>> y = rng.random(10)
>>> w = rng.random(10)

>>> da = CentralMomentsArray.zeros(val_shape=(2,), mom=(2, 2))
>>> da.push_vals(x, y, weight=w, axis=0)
<CentralMomentsArray(mom_ndim=2)>
array([[[ 5.4367e+00,  6.0656e-01,  9.9896e-02],
        [ 6.4741e-01,  3.3791e-02, -5.1117e-03],
        [ 5.0888e-02, -1.0060e-02,  7.0290e-03]],

       [[ 5.4367e+00,  6.0656e-01,  9.9896e-02],
        [ 3.9793e-01,  6.3224e-03, -2.2669e-02],
        [ 9.3979e-02,  9.9433e-04,  6.5765e-03]]])

Which is the same as

>>> cmomy.wrap_reduce_vals(x, y, weight=w, mom=(2, 2), axis=0)
<CentralMomentsArray(mom_ndim=2)>
array([[[ 5.4367e+00,  6.0656e-01,  9.9896e-02],
        [ 6.4741e-01,  3.3791e-02, -5.1117e-03],
        [ 5.0888e-02, -1.0060e-02,  7.0290e-03]],

       [[ 5.4367e+00,  6.0656e-01,  9.9896e-02],
        [ 3.9793e-01,  6.3224e-03, -2.2669e-02],
        [ 9.3979e-02,  9.9433e-04,  6.5765e-03]]])
__add__(other)[source]#

Add objects to new object.

__iadd__(other)[source]#

Self adder.

__imul__(scale)[source]#

Inplace multiply.

__isub__(other)[source]#

Inplace subtraction.

__mul__(scale)[source]#

New object with weight scaled by scale.

__sub__(other)[source]#

Subtract objects.

assign_moment(moment=None, *, squeeze=True, copy=True, dim_combined=None, keep_attrs=None, apply_ufunc_kwargs=None, **moment_kwargs)[source]#

Create object with update weight, average, etc.

Parameters:

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

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

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

  • 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 (Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]], DataArray, Dataset]) – Keyword argument form of moment. Must provide either moment or moment_kwargs.

Returns:

output (object) – Same type as self with updated data.

See also

utils.assign_moment

cmom()[source]#

Central moments.

Strict central moments of the form

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

where

\[\langle x \rangle = \sum_i w_i x_i / \sum_i w_i\]
Returns:

output (ndarray or DataArray)

copy()[source]#

Create a new object with copy of data.

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

cov()[source]#

Covariance (or variance if mom_ndim==1).

mean(squeeze=True)[source]#

Mean (first moment).

property mom#

Moments tuple.

property mom_ndim#

Number of moment dimensions.

property mom_params#

Moments parameters object.

property mom_shape#

Shape of moments dimensions.

moveaxis(axis=MISSING, dest=MISSING, *, dim=MISSING, dest_dim=MISSING, axes_to_end=False)[source]#

Generalized moveaxis

Parameters:
Returns:

output (object) – Object with moved axes. This is a view of the original data.

See also

utils.moveaxis, numpy.moveaxis

property ndim#

Total number of dimensions.

property obj#

Underlying object.

pipe(func_or_method, *args, _reorder=True, _copy=None, _verify=False, _fastpath=False, **kwargs)[source]#

Apply func_or_method to underlying data and wrap results in new wrapped object.

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

Note that a ValueError will be raised if last dimension(s) do not have the same shape as self.mom_shape.

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

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

  • _reorder (bool, default True) – If True, reorder the data such that mom_dims are last. Only applicable for DataArray like underlying data.

  • _copy (bool, default False) – If True, copy the resulting data. Otherwise, try to use a view.

  • _order (str, optional) – Array order to apply to output.

  • _verify (bool, default False)

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

Returns:

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

Notes

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

rmom()[source]#

Raw moments.

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

where

\[\langle x \rangle = \sum_i w_i x_i / \sum_i w_i\]
Returns:

raw_moments (ndarray or DataArray)

See also

to_raw, convert.moments_type, cmom

select_moment(name, *, squeeze=True, dim_combined='variable', coords_combined=None, keep_attrs=None, apply_ufunc_kwargs=None)[source]#

Select specific 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.

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

See also

utils.select_moment

property shape#

Shape of wrapped object.

std(squeeze=True)[source]#

Standard deviation (ddof=0).

to_raw(*, weight=None)[source]#

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}\]

where

\[\langle x \rangle = \sum_i w_i x_i / \sum_i w_i\]
Returns:

raw (ndarray or DataArray)

See also

wrap_raw, convert.moments_type

property val_ndim#

Number of values dimensions (ndim - mom_ndim).

property val_shape#

Shape of values dimensions.

var(squeeze=True)[source]#

Variance (second central moment).

weight()[source]#

Weight data.

zeros_like()[source]#

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

cumulative(*, axis=MISSING, axes_to_end=False, out=None, dtype=None, casting='same_kind', order=None, parallel=None)[source]#

Convert to cumulative moments.

Parameters:

  • axis (int, optional) – Axis to reduce/sample along. Note that negative values are relative to data.ndim - mom_ndim. It is assumed that the last dimensions are for moments. For example, if data.shape == (1,2,3) with mom_ndim=1, axis = -1 `` would be equivalent to ``axis = 1. Defaults to axis=-1.

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

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

Returns:

output (numpy.ndarray) – Same type as self.obj, with moments accumulated over axis.

See also

convert.cumulative

moments_to_comoments(*, mom, dtype=None, order=None)[source]#

Convert moments (mom_ndim=1) to comoments (mom_ndim=2).

Parameters:

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

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

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

See also

convert.moments_to_comoments

Returns:

output (CentralMomentsArray) – Same type as self with mom_ndim=2.

resample_and_reduce(*, axis=-1, sampler, axes_to_end=False, out=None, dtype=None, casting='same_kind', order=None, parallel=None)[source]#

Bootstrap resample and reduce.

Parameters:

  • axis (int, optional) – Axis to reduce/sample along. Note that negative values are relative to data.ndim - mom_ndim. It is assumed that the last dimensions are for moments. For example, if data.shape == (1,2,3) with mom_ndim=1, axis = -1 `` would be equivalent to ``axis = 1. Defaults to axis=-1.

  • sampler (int or array-like or IndexSampler or mapping) – Passed through resample.factory_sampler() to create an IndexSampler. Value can either be nrep (the number of replicates), freq (frequency array), a IndexSampler object, or a mapping of parameters. The mapping can have form of FactoryIndexSamplerKwargs. Allowable keys are freq, indices, ndat, nrep, nsamp, paired, rng, replace, shuffle.

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

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

Returns:

output (object) – Instance of calling class. Note that new object will have (...,shape[axis-1], nrep, shape[axis+1], ...), where nrep is the number of replicates.

See also

CentralMomentsData.resample_and_reduce

Examples

>>> import cmomy
>>> rng = cmomy.default_rng(0)
>>> c = cmomy.CentralMomentsArray(rng.random((3, 3)), mom_ndim=1)
>>> c
<CentralMomentsArray(mom_ndim=1)>
array([[0.637 , 0.2698, 0.041 ],
       [0.0165, 0.8133, 0.9128],
       [0.6066, 0.7295, 0.5436]])

>>> c.resample_and_reduce(axis=0, sampler=dict(nrep=5, rng=0))
<CentralMomentsArray(mom_ndim=1)>
array([[0.6397, 0.7338, 0.563 ],
       [1.9109, 0.2698, 0.041 ],
       [1.9109, 0.2698, 0.041 ],
       [1.2298, 0.7306, 0.5487],
       [0.6397, 0.7338, 0.563 ]])
jackknife_and_reduce(*, data_reduced=None, axis=-1, axes_to_end=False, out=None, dtype=None, casting='same_kind', order=None, parallel=None)[source]#

Jackknife resample and reduce

Parameters:

  • data_reduced (array or CentralMomentsArray) – Data reduced along axis. Array of same type as self.obj or same type as self.

  • axis (int, optional) – Axis to reduce/sample along. Note that negative values are relative to data.ndim - mom_ndim. It is assumed that the last dimensions are for moments. For example, if data.shape == (1,2,3) with mom_ndim=1, axis = -1 `` would be equivalent to ``axis = 1. Defaults to axis=-1.

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

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

Returns:

object – Instance of calling class with jackknife resampling along axis.

See also

jackknife_data

reduce(axis=MISSING, *, by=None, block=None, axes_to_end=False, out=None, dtype=None, casting='same_kind', order=None, keepdims=False, parallel=None)[source]#

Create new object reduce along axis.

Parameters:

  • axis (int, optional) – Axis to reduce/sample along. Note that negative values are relative to data.ndim - mom_ndim. It is assumed that the last dimensions are for moments. For example, if data.shape == (1,2,3) with mom_ndim=1, axis = -1 `` would be equivalent to ``axis = 1. Defaults to axis=-1.

  • by (array-like of int) – Groupby values of same length as data along sampled dimension. Negative values indicate no group (i.e., skip this index).

  • block (int, optional) – If specified, perform block average reduction with blocks of this size. Negative values are transformed to all data.

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

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

  • keepdims (bool) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

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

Returns:

output (CentralMomentsArray) – If by is None, reduce all samples along axis, optionally keeping axis with size 1 if keepdims=True. Otherwise, reduce for each unique value of by. In this case, output will have shape (..., shape[axis-1], ngroup, shape[axis+1], ...) where ngroups = np.max(by) + 1 is the number of unique positive values in by.

See also

reduce_data, reduce_data_grouped, reduce_data_indexed, block_by

classmethod zeros(*, mom, val_shape=None, dtype=None, order=None)[source]#

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

Returns:

output (CentralMomentsArray) – New instance with zero values.

See also

numpy.zeros

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

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

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

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

reshape(shape, *, order=None)[source]#

Create a new object with reshaped data.

Parameters:

  • shape (int or tuple) – shape of values part of data.

  • order ({"C", "F", "A"}, optional) – Parameter to numpy.reshape(). Note that this parameter has nothing to do with the output data order. Rather, it is how the data is read for the reshape.

Returns:

output (CentralMomentsArray) – Output object with reshaped data. This will be a view if possilble; otherwise, it will be copy.

See also

numpy.reshape, new_like

Examples

>>> import cmomy
>>> rng = cmomy.default_rng(0)
>>> da = cmomy.wrap_reduce_vals(rng.random((10, 2, 3)), mom=2, axis=0)
>>> da
<CentralMomentsArray(mom_ndim=1)>
array([[[10.    ,  0.5205,  0.0452],
        [10.    ,  0.4438,  0.0734],
        [10.    ,  0.5038,  0.1153]],

       [[10.    ,  0.5238,  0.1272],
        [10.    ,  0.628 ,  0.0524],
        [10.    ,  0.412 ,  0.0865]]])

>>> da.reshape(shape=(-1,))
<CentralMomentsArray(mom_ndim=1)>
array([[10.    ,  0.5205,  0.0452],
       [10.    ,  0.4438,  0.0734],
       [10.    ,  0.5038,  0.1153],
       [10.    ,  0.5238,  0.1272],
       [10.    ,  0.628 ,  0.0524],
       [10.    ,  0.412 ,  0.0865]])
resample(indices, *, axis=-1, last=False)[source]#

Create a new object sampled from index.

Parameters:

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

  • axis (int, optional) – Axis to reduce/sample along. Note that negative values are relative to data.ndim - mom_ndim. It is assumed that the last dimensions are for moments. For example, if data.shape == (1,2,3) with mom_ndim=1, axis = -1 `` would be equivalent to ``axis = 1. Defaults to axis=-1.

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

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

Returns:

output (object) – Instance of calling class. The new object will have shape (..., shape[axis-1], nrep, nsamp, shape[axis+1], ...), (if last=False) or shape (..., shape[axis-1], shape[axis+1], ..., nrep, nsamp, mom_0, ...) (if last=True), where shape=self.obj.shape and nrep, nsamp = indices.shape.

fill(value=0)[source]#

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()[source]#

Zero out underlying data.

Returns:

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

See also

fill

to_dataarray(*, dims=None, attrs=None, coords=None, name=None, mom_dims=None, template=None, copy=False)[source]#

Create a CentralMomentsData object from self.

Parameters:

  • dims (hashable or sequence of hashable) –

    Dimension of resulting xarray.DataArray.

    • If len(dims) == self.ndim, then dims specifies all dimensions.

    • If len(dims) == self.val_ndim, dims = dims + mom_dims

    Default to ('dim_0', 'dim_1', ...)

  • attrs (mapping) – Attributes of output

  • coords (mapping) – Coordinates of output

  • name (hashable) – Name of output

  • indexes (Any) – indexes attribute. This is ignored.

  • template (DataArray) – If present, output will have attributes of template. Overrides other options.

  • copy (bool) – If True, copy the data. If False, return a view if possible.

Returns:

output (DataArray)

Examples

>>> from cmomy.random import default_rng
>>> rng = default_rng(0)
>>> c = CentralMomentsArray(rng.random((1, 2, 4)), mom_ndim=1)
>>> c
<CentralMomentsArray(mom_ndim=1)>
array([[[0.637 , 0.2698, 0.041 , 0.0165],
        [0.8133, 0.9128, 0.6066, 0.7295]]])

Default is to create a CentralMomentsData object

>>> c.to_dataarray()
<CentralMomentsData(mom_ndim=1)>
<xarray.DataArray (dim_0: 1, dim_1: 2, mom_0: 4)> Size: 64B
array([[[0.637 , 0.2698, 0.041 , 0.0165],
        [0.8133, 0.9128, 0.6066, 0.7295]]])
Dimensions without coordinates: dim_0, dim_1, mom_0

To just create a xarray.DataArray object, access obj

>>> c.to_dataarray().obj
<xarray.DataArray (dim_0: 1, dim_1: 2, mom_0: 4)> Size: 64B
array([[[0.637 , 0.2698, 0.041 , 0.0165],
        [0.8133, 0.9128, 0.6066, 0.7295]]])
Dimensions without coordinates: dim_0, dim_1, mom_0

You can set attributes during construction:

>>> c.to_dataarray(dims=["a", "b", "mom"])
<CentralMomentsData(mom_ndim=1)>
<xarray.DataArray (a: 1, b: 2, mom: 4)> Size: 64B
array([[[0.637 , 0.2698, 0.041 , 0.0165],
        [0.8133, 0.9128, 0.6066, 0.7295]]])
Dimensions without coordinates: a, b, mom
to_x(*, dims=None, attrs=None, coords=None, name=None, mom_dims=None, template=None, copy=False)[source]#

Alias to to_dataarray()

Contents