Metadata-Version: 2.4
Name: gamrs
Version: 0.17.4
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7 ; extra == 'quantile'
Provides-Extra: quantile
License-File: LICENSE
Summary: Generalised additive models in Rust, with a Python API; a reimplementation of R's mgcv
Keywords: statistics,gam,mgcv,regression,splines,smoothing
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/AlekJaworski/gamrs/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/AlekJaworski/gamrs/issues
Project-URL: Repository, https://github.com/AlekJaworski/gamrs

# gamrs

[![PyPI](https://img.shields.io/pypi/v/gamrs)](https://pypi.org/project/gamrs/)
[![CI](https://github.com/AlekJaworski/gamrs/actions/workflows/ci.yml/badge.svg)](https://github.com/AlekJaworski/gamrs/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

Generalised additive models in Rust, with a Python API. gamrs reimplements
R's [mgcv](https://cran.r-project.org/package=mgcv): the same bases,
penalties and REML criterion, tested against mgcv's own output.

```bash
pip install gamrs
```

Wheels for Linux, macOS and Windows, Python 3.9 and later.

## Example

```python
import numpy as np
import pandas as pd
from gamrs import Gam, CrTerm, TeTerm, ReTerm

rng = np.random.default_rng(0)
n = 2_000
df = pd.DataFrame({
    "x": rng.uniform(0, 10, n),
    "u": rng.uniform(0, 1, n),
    "v": rng.uniform(0, 1, n),
    "g": rng.integers(0, 50, n),
})
y = np.sin(df.x) + df.u * df.v + rng.normal(0, 0.3, 50)[df.g] + rng.normal(0, 0.3, n)

# y ~ s(x, bs = "cr") + te(u, v) + s(g, bs = "re")
gam = Gam(
    terms=[CrTerm("x", k=10), TeTerm(cols=("u", "v"), k=(5, 5)), ReTerm("g")],
    method="REML",
).fit(df, y)

gam.predict(df)
mu, lo, hi = gam.predict_ci(df, level=0.95)
gam.edf_, gam.lambda_, gam.reml_value_
```

More in [docs/quickstart.md](docs/quickstart.md).

## What it fits

| gamrs | mgcv |
| --- | --- |
| `CrTerm("x", k=10)` | `s(x, bs = "cr")` |
| `TpsTerm(cols=("x", "z"))` | `s(x, z, bs = "tp")` |
| `TeTerm(cols=("x", "z"))`, `TiTerm(cols=...)` | `te(x, z)`, `ti(...)`, any number of margins |
| `ReTerm("g")` | `s(g, bs = "re")` |
| `ScTerm("x", "increasing")`, `TeScTerm(...)` | `s(x, bs = "sc")`, `te(..., bs = "sc")` as fitted by `scasm()` |
| `ParametricTerm("x")` | a linear term |
| `by=` on `CrTerm`, `TeTerm`, `ReTerm` | `s(x, by = w)` |

**Families:** `gaussian`, `binomial`, `poisson`, `quasipoisson`, `quasibinomial`,
`Gamma`, `inverse_gaussian`, `nb`, `tw`, `scat`, `ocat`. Also quantile
regression in the style of `qgam` (`fit_quantile`) and the location–scale
families `gaulss` (`fit_gaulss`) and `shash` (`fit_shash`).

Fitted models expose `predict`, `predict_ci`, `coef_`, `vcov_`, `edf_`,
`lambda_` and `fit_stats_`, and serialise for inference-only use with
`GamPredictor`.

## Agreement with mgcv

Every family and term type has parity tests against fixtures generated by
mgcv 1.9-4 ([`scripts/r/`](scripts/r), [`tests/`](tests)). Two deliberate
differences:

- `method="fREML"` selects Fellner–Schall smoothing-parameter updates, as in
  mgcv's `gam(optimizer = "efs")` (GLM families; others fall back to Newton
  with a warning). It is not `bam(method = "fREML")`, which runs Newton.
  Both optimise the REML criterion, so results match `gam(method = "REML")`.
- Monotone (`sc`) terms choose their smoothing parameters by the REML that
  `scasm()` reports, not the reduced criterion it iterates on. That criterion
  jumps where a constraint starts or stops binding, so `scasm()` can stop
  without converging. At the same smoothing parameters gamrs and `scasm()`
  agree to about 1e-12.

## Speed

A random effect plus four smooths, one thread, Intel i7-8565U, mgcv 1.9-4.
Seconds per fit.

| Model | mgcv `gam` | mgcv `bam` | gamrs 0.17 |
| --- | ---: | ---: | ---: |
| Gaussian, n = 20,000, 100 levels | 15.8 | 0.49 | 0.08 |
| Gaussian, n = 2,000, 1,000 levels | 63.5 | 6.85 | 1.12 |
| Gaussian, n = 20,000, 1,000 levels | — | 15.1 | 2.03 |
| Poisson, n = 20,000, 50 levels | 6.59 | 1.22 | 0.81 |
| Poisson, n = 20,000, 1,000 levels | — | 102 | 4.21 |
| Scaled t, n = 20,000, 50 levels | 10.8 | 1.86 | 1.51 |
| Scaled t, n = 20,000, 1,000 levels | — | 239 | 9.67 |

— not run. gamrs's fitted values are within 4e-4 standard deviations of
`gam`'s. `bam(discrete = TRUE)` is faster on the 50-level models, but its
fitted values are 0.5–1.6% of a standard deviation away from `gam`'s.

Fits release the GIL, so independent fits run in parallel on Python threads.
Set `OPENBLAS_NUM_THREADS=1` when running several at once.

## Rust

The core is a Rust crate. Bases, families, the inner penalised fit and the
REML outer search are separate layers (`src/basis`, `src/family`,
`src/inner`, `src/score`, `src/fit`), and the Python package is a thin PyO3
layer over them.

## License

MIT. Release notes are in the [changelog](CHANGELOG.md).

