cmomy

A Python package to calculate and manipulate Central (co)moments. The main features of cmomy are as follows:

• Numba accelerated computation of central moments and co-moments
• Routines to combine, and resample central moments.
• Supports numpy array and xarray DataArray or Dataset based data.
• Routines to convert between central and raw moments.

Overview

cmomy is an open source package to calculate central moments and co-moments in a numerical stable and direct way. Behind the scenes, cmomy makes use of Numba to rapidly calculate moments. A good introduction to the type of formulas used can be found here.

Features

• Fast calculation of central moments and central co-moments with weights
• Support for scalar or vector inputs
• numpy and xarray api's
• bootstrap resampling

Status

This package is actively used by the author. Please feel free to create a pull request for wanted features and suggestions!

Quick start

Use one of the following

pip install cmomy

or

conda install -c conda-forge cmomy

Example usage

>>> import numpy as np
>>> import cmomy
>>> rng = cmomy.default_rng(seed=0)
>>> x = rng.random(100)
>>> m = x.mean()
>>> mom = np.array([((x - m) ** i).mean() for i in range(4)])
>>> c = cmomy.wrap_reduce_vals(x, mom=3, axis=0)

>>> np.testing.assert_allclose(c.cmom(), mom, atol=1e-8)
>>> c.cmom()
array([ 1.    ,  0.    ,  0.0919, -0.0061])

# break up into chunks
>>> c = cmomy.wrap_reduce_vals(x.reshape(-1, 2), mom=3, axis=0)

>>> c
<CentralMomentsArray(mom_ndim=1)>
array([[ 5.0000e+01,  5.3019e-01,  8.0115e-02, -4.3748e-03],
       [ 5.0000e+01,  5.6639e-01,  1.0297e-01, -8.9911e-03]])

# Reduce along an axis
>>> c.reduce(axis=0).cmom()
array([ 1.    ,  0.    ,  0.0919, -0.0061])

# unequal chunks
>>> x0, x1, x2 = x[:20], x[20:60], x[60:]

>>> cs = [cmomy.wrap_reduce_vals(_, mom=3, axis=0) for _ in (x0, x1, x2)]

>>> c = cs[0] + cs[1] + cs[2]

>>> np.testing.assert_allclose(c.cmom(), mom, atol=1e-8)
>>> c.cmom()
array([ 1.    ,  0.    ,  0.0919, -0.0061])

Note on caching

This code makes extensive use of the numba python package. This uses a jit compiler to speed up vital code sections. This means that the first time a function called, it has to compile the underlying code. However, caching has been implemented. Therefore, the very first time you run a function, it may be slow. But all subsequent uses (including other sessions) will be already compiled.

Documentation

See the documentation for a look at cmomy in action.

License

This is free software. See LICENSE.

Related work

This package is used extensively in the newest version of thermoextrap. See here.

Contact

The author can be reached at wpk@nist.gov.

Credits

This package was created using Cookiecutter with the usnistgov/cookiecutter-nist-python template.