Skip to content

Latest commit

 

History

History
154 lines (118 loc) · 5.43 KB

README.md

File metadata and controls

154 lines (118 loc) · 5.43 KB
Raw

Lmo - Trimmed L-moments and L-comoments

Lmo - PyPI Lmo - Python versions Lmo - SPEC 0 Lmo - BSD License Lmo - CI Lmo - pre-commit Lmo - ruff Lmo - bassedpyright

Unlike the legacy product-moments, the L-moments uniquely describe a probability distribution, and are more robust and efficient.

The "L" stands for Linear; it is a linear combination of order statistics. So Lmo is as fast as sorting your samples (in terms of time-complexity).

Key Features

  • Calculates trimmed L-moments and L-comoments, from samples or any scipy.stats distribution.
  • Full support for trimmed L-moment (TL-moments), e.g. lmo.l_moment(..., trim=(1/137, 3.1416)).
  • Generalized Method of L-moments: robust distribution fitting that beats MLE.
  • Fast estimation of L-comoment matrices from your multidimensional data or multivariate distribution.
  • Goodness-of-fit test, using L-moment or L-moment ratio's.
  • Exact (co)variance structure of the sample- and population L-moments.
  • Theoretical & empirical influence functions of L-moments & L-ratio's.
  • Complete docs, including detailed API reference with usage examples and with mathematical $\TeX$ definitions.
  • Clean Pythonic syntax for ease of use.
  • Vectorized functions for very fast fitting.
  • Fully typed, tested, and tickled.
  • Optional Pandas integration.

Quick example

Even if your data is pathological like Cauchy, and the L-moments are not defined, the trimmed L-moments (TL-moments) can be used instead.

Let's calculate the first two TL-moments (the TL-location and the TL-scale) of a small amount of samples drawn from the standard Cauchy distribution:

>>> import numpy as np
>>> import lmo
>>> rng = np.random.default_rng(1980)
>>> data = rng.standard_cauchy(96)
>>> lmo.l_moment(data, [1, 2], trim=1)
array([-0.17937038,  0.68287665])

Compared with the theoretical standard Cauchy TL-moments, that pretty close!

>>> from scipy.stats import cauchy
>>> cauchy.l_moment([1, 2], trim=1)
array([0.        , 0.69782723])

Now let's try this again using the first two conventional moments, i.e. the mean and the standard deviation:

>>> from scipy.stats import moment
>>> np.r_[data.mean(), data.std()]
array([-1.7113441 , 19.57350731])

So even though the data was drawn from the standard Cauchy distribution, we can immediately see that this look standard at all.

The reason is that the Cauchy distribution doesn't have a mean or standard deviation:

>>> np.r_[cauchy.mean(), cauchy.std()]
array([nan, nan])

See the documentation for more examples and the API reference.

Installation

Lmo is available on PyPI, and can be installed with:

pip install lmo

Roadmap

  • Automatic trim-length selection.
  • Plotting utilities (deps optional), e.g. for L-moment ratio diagrams.

Dependencies

These are automatically installed by your package manager when installing Lmo.

version
python >=3.11
numpy >=1.25.2
scipy >=1.11.4

Additionally, Lmo supports the following optional packages:

version pip install _
pandas >=2.0 Lmo[pandas]

See SPEC 0 for more information.

Foundational Literature