Metadata-Version: 2.4
Name: gamfit
Version: 0.1.20
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Dist: numpy>=1.26 ; extra == 'all'
Requires-Dist: pandas>=2.0 ; extra == 'all'
Requires-Dist: pyarrow>=14 ; extra == 'all'
Requires-Dist: matplotlib>=3.8 ; extra == 'all'
Requires-Dist: scikit-learn>=1.4 ; extra == 'all'
Requires-Dist: numpy>=1.26 ; extra == 'numpy'
Requires-Dist: pandas>=2.0 ; extra == 'pandas'
Requires-Dist: pyarrow>=14 ; extra == 'pandas'
Requires-Dist: matplotlib>=3.8 ; extra == 'plot'
Requires-Dist: scikit-learn>=1.4 ; extra == 'sklearn'
Requires-Dist: numpy>=1.26 ; extra == 'sklearn'
Requires-Dist: pytest>=8 ; extra == 'test'
Requires-Dist: numpy>=1.26 ; extra == 'test'
Requires-Dist: pandas>=2.0 ; extra == 'test'
Requires-Dist: pyarrow>=14 ; extra == 'test'
Requires-Dist: matplotlib>=3.8 ; extra == 'test'
Requires-Dist: scikit-learn>=1.4 ; extra == 'test'
Requires-Dist: mypy>=1.18 ; extra == 'type'
Requires-Dist: numpy>=1.26 ; extra == 'type'
Requires-Dist: pandas>=2.0 ; extra == 'type'
Requires-Dist: pandas-stubs ; extra == 'type'
Requires-Dist: pyarrow>=14 ; extra == 'type'
Requires-Dist: polars>=1 ; extra == 'type'
Requires-Dist: matplotlib>=3.8 ; extra == 'type'
Requires-Dist: scikit-learn>=1.4 ; extra == 'type'
Requires-Dist: scikit-learn-stubs ; extra == 'type'
Requires-Dist: scipy-stubs ; extra == 'type'
Requires-Dist: pytest>=8 ; extra == 'type'
Requires-Dist: types-requests ; extra == 'type'
Requires-Dist: vulture>=2.16 ; extra == 'type'
Provides-Extra: all
Provides-Extra: numpy
Provides-Extra: pandas
Provides-Extra: plot
Provides-Extra: sklearn
Provides-Extra: test
Provides-Extra: type
License-File: LICENSE
Summary: Formula-first generalized additive models with a high-performance Rust core
Keywords: gam,gamfit,generalized-additive-models,regression,smoothing-splines,thin-plate-spline,reml,statistics,machine-learning,rust
Author: SauersML
License-Expression: AGPL-3.0-or-later
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/SauersML/gam/releases
Project-URL: Homepage, https://github.com/SauersML/gam
Project-URL: Issues, https://github.com/SauersML/gam/issues
Project-URL: Repository, https://github.com/SauersML/gam

# gamfit

[![PyPI](https://img.shields.io/pypi/v/gamfit.svg)](https://pypi.org/project/gamfit/)
[![Python](https://img.shields.io/pypi/pyversions/gamfit.svg)](https://pypi.org/project/gamfit/)
[![License](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](https://github.com/SauersML/gam/blob/main/LICENSE)

A formula-first generalized additive model library for Python, backed by a
high-performance Rust engine.

`gamfit` fits Gaussian, binomial, Poisson, and Gamma GLMs with smooth terms,
random effects, location-scale extensions, survival likelihoods, and
flexible/learnable links. Smoothing parameters are selected by REML or LAML.
Posterior sampling uses NUTS.

## Install

```bash
uv add gamfit
```

Or with a managed Python (one-off, no project required):

```bash
uv pip install gamfit
```

Wheels are published for Linux (x86_64, aarch64), macOS (x86_64, Apple
silicon), and Windows. No Rust toolchain required.

## Quick start

```python
import gamfit

train = [
    {"y": 1.2, "x": 0.0},
    {"y": 1.9, "x": 1.0},
    {"y": 3.1, "x": 2.0},
    {"y": 4.5, "x": 3.0},
]

model = gamfit.fit(train, "y ~ s(x)")
predictions = model.predict([{"x": 1.5}, {"x": 2.5}], interval=0.95)
print(model.summary())
model.save("model.gam")
```

Pandas, pyarrow, dict-of-columns, and list-of-records inputs all work
without conversion.

## What's different

- **Three-part penalty structure.** Each smooth gets separate penalties
  for magnitude, gradient, and curvature. Most GAM libraries use one
  (curvature only) or two; the three-part decomposition gives the
  smoother more degrees of freedom to distinguish flat-but-offset
  functions from wiggly ones.
- **Flexible link functions.** A spline offset from a base link (e.g.
  probit) lets the data correct for link misspecification while
  encoding the belief that the base link is approximately right.
- **Surface smooths.** Thin-plate splines, Duchon radial bases with
  triple-operator regularization, and Matérn covariance smooths in
  arbitrary dimension, with automatic knot placement.
- **Adaptive anisotropy.** Per-axis spatial anisotropy lets the model
  shrink or stretch each feature axis independently within a single
  joint smooth.
- **Composable basis/kernel.** Mix and match the kernel of one spline
  family with the length-scale behavior of another (e.g. Duchon kernel
  with Matérn-style global κ scaling).

## scikit-learn integration

```python
from gamfit.sklearn import GAMRegressor

est = GAMRegressor(formula="y ~ s(x)")
est.fit(train)
preds = est.predict([{"x": 1.5}, {"x": 2.5}])
```

## Public API

| Symbol | Purpose |
| --- | --- |
| `gamfit.fit(data, formula, **kwargs)` | Fit a model from a dataset and a Wilkinson-style formula. |
| `gamfit.load(path)` / `gamfit.loads(bytes)` | Reload a saved model. |
| `gamfit.validate_formula(data, formula, ...)` | Type-check a formula against a dataset without fitting. |
| `gamfit.build_info()` | Native-extension build metadata. |
| `gamfit.explain_error(exc)` | Convert a `gamfit` exception into a human-readable hint. |
| `gamfit.Model` | Fitted-model handle: `predict`, `summary`, `check`, `diagnose`, `plot`, `report`, `save`. |
| `gamfit.sklearn.GAMRegressor` / `GAMClassifier` | scikit-learn-compatible estimators. |

See the [project documentation](https://github.com/SauersML/gam) for the
full guide, the formula DSL reference, and the CLI.

## Optional extras

```bash
uv add "gamfit[pandas]"     # pandas + pyarrow input/output
uv add "gamfit[plot]"       # matplotlib-based plotting
uv add "gamfit[sklearn]"    # scikit-learn integration
uv add "gamfit[all]"        # everything
```

## License

AGPL-3.0-or-later. See [LICENSE](https://github.com/SauersML/gam/blob/main/LICENSE).
A commercial license is available for closed-source or SaaS use — see
[COMMERCIAL.md](https://github.com/SauersML/gam/blob/main/COMMERCIAL.md).

