Metadata-Version: 2.4
Name: gibbus
Version: 0.2.0
Summary: Flexible maximum-likelihood modeling of smooth univariate log-concave distributions
Author: Daniel Salib
Maintainer: Daniel Salib
License-Expression: MIT
Project-URL: Homepage, https://github.com/DanJSal/gibbus
Project-URL: Repository, https://github.com/DanJSal/gibbus
Project-URL: Issues, https://github.com/DanJSal/gibbus/issues
Keywords: statistics,probability,log-concave,density estimation,maximum likelihood,mixture models,censored data,survival analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Cython
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Provides-Extra: test
Requires-Dist: mpmath>=1.3; extra == "test"
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-xdist>=3.0; extra == "test"
Requires-Dist: sympy>=1.12; extra == "test"
Dynamic: license-file

# gibbus

[![PyPI](https://img.shields.io/pypi/v/gibbus.svg)](https://pypi.org/project/gibbus/)
[![Python](https://img.shields.io/pypi/pyversions/gibbus.svg)](https://pypi.org/project/gibbus/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Gibbus is a Python library for fitting smooth univariate probability
distributions to data. Instead of committing to a parametric family, it fits a
flexible log-concave density by maximum likelihood. One model covers shapes
that would otherwise call for a normal, gamma, beta, Weibull, Gumbel, or
something in between. Multimodal data is fitted as a mixture of log-concave
components.

![Gibbus fits to four simulated datasets](docs/images/readme-examples.png)

*Fits to simulated data. The bounded and censored fits enable the boundary
terms for endpoints where the density falls to zero; the others use default
settings. The figure is generated by
[readme_figure.py](docs/images/readme_figure.py).*

## Installation

```bash
pip install gibbus
```

Gibbus requires Python 3.11 or later, NumPy and SciPy; binary wheels cover
Linux x86-64, Windows x86-64 and macOS. Version 0.2 replaces the 0.1 model:
its options, diagnostics and saved format differ (see the
[changelog](CHANGELOG.md)). See [Getting started](docs/getting-started.md)
for source builds and [Development](docs/development.md) for an editable
install with the test dependencies.

## Example

```python
import numpy as np
from gibbus import Distribution

rng = np.random.default_rng(0)
samples = rng.gamma(2.5, size=400)

model = Distribution().fit(samples, support=(0, np.inf))

model.pdf([0.5, 2.0, 5.0])
model.cdf(2.0)
model.ppf(0.99)
model.mean, model.std
model.sample(100, rng=rng)
```

Interval-censored observations are given as `[lower, upper]` rows, with an
infinite bound for left or right censoring. Mixtures take a fixed number of
components or `"auto"`.

```python
intervals = np.column_stack([np.floor(samples), np.floor(samples) + 1])
intervals[samples > 6] = [6, np.inf]
censored = Distribution().fit(intervals, support=(0, np.inf))

bimodal = np.r_[rng.normal(-2, 0.5, 300), rng.normal(2, 0.7, 300)]
mixture = Distribution().fit(bimodal, n_components="auto", rng=0)
mixture.weights
```

## Features

- Exact, interval-censored, and left- or right-censored observations, with
  optional weights
- Full-line, half-line, and bounded supports, including densities that fall
  to zero at a boundary, as gamma and beta densities do
- Mixtures with a fixed or automatically chosen number of components
- Tail probabilities and extreme quantiles that remain accurate far past the
  point where `1 - cdf` loses precision
- Moments, entropy, survival and hazard functions, sampling, affine
  transforms, and truncation
- Goodness-of-fit tests, bootstrap confidence bands, and fit diagnostics
- Fitted models saved as plain NumPy arrays that load without pickle

## How it works

Each component has density proportional to `exp(-V(x))`, where `V` is a
combination of polynomial, boundary, and tail terms. The fit maximizes the
likelihood subject to `V` being convex over the whole support, which is the
condition for log-concavity; convexity is checked numerically, to a small
recorded threshold, by a search over the whole support including the tails.
The polynomial degree, and with it the flexibility of the fit, is chosen from
the data. The fitted density is a
closed-form function rather than a grid or a sum of kernels.

See [Modeling concepts](docs/modeling-concepts.md) for details.

## Documentation

- [Getting started](docs/getting-started.md)
- [Fitting](docs/fitting.md)
- [Using fitted distributions](docs/using-distributions.md)
- [Diagnostics](docs/diagnostics.md)
- [All documentation](docs/README.md)

## Citation and license

Citation information is in [CITATION.cff](CITATION.cff). Gibbus is released
under the [MIT license](LICENSE). Contributions are welcome; see
[CONTRIBUTING.md](CONTRIBUTING.md).
