gamfit
Formula-based generalized additive models for Python, backed by a Rust engine.
gamfit fits Gaussian, binomial (including Bernoulli marginal-slope),
Poisson, negative-binomial, Gamma, Beta, Tweedie, and multinomial GLMs
with smooth terms, random effects,
bounded/constrained coefficients, location-scale extensions, survival
likelihoods, and flexible/learnable links. Smoothing parameters are
selected by REML or LAML. Posterior sampling uses NUTS where supported,
and a Gaussian Laplace approximation otherwise.
Manifold smooths handle predictor spaces that wrap or close: circles, cylinders, tori, and the sphere (intrinsic Wahba and spherical-harmonic kernels), plus periodic tensor products and boundary-conditioned B-splines. The Möbius example in the gallery is a 4π-periodic double-cover parameterization, not a twisted Möbius-strip basis.
Docs: https://gamfit.readthedocs.io/.
Install
uv add gamfit
Wheels are published for Linux (x86_64, aarch64), macOS (x86_64, Apple silicon), and Windows. No Rust toolchain is required.
Example
import gamfit
# Smooth fits need enough rows for the basis to be identified; ~20 rows
# is the minimum the default `s(x)` basis (cubic B-spline) is well-posed
# on. Use more rows when the signal is noisier.
train = [
{"y": 1.05, "x": 0.0}, {"y": 1.32, "x": 0.5}, {"y": 1.78, "x": 1.0},
{"y": 2.41, "x": 1.5}, {"y": 3.10, "x": 2.0}, {"y": 3.95, "x": 2.5},
{"y": 4.80, "x": 3.0}, {"y": 5.62, "x": 3.5}, {"y": 6.25, "x": 4.0},
{"y": 6.71, "x": 4.5}, {"y": 6.94, "x": 5.0}, {"y": 6.88, "x": 5.5},
{"y": 6.55, "x": 6.0}, {"y": 5.99, "x": 6.5}, {"y": 5.20, "x": 7.0},
{"y": 4.30, "x": 7.5}, {"y": 3.42, "x": 8.0}, {"y": 2.65, "x": 8.5},
{"y": 2.10, "x": 9.0}, {"y": 1.82, "x": 9.5},
]
model = gamfit.fit(train, "y ~ s(x)")
print(model.predict([{"x": 1.5}, {"x": 5.0}], interval=0.95))
print(model.summary())
model.save("model.gam")
pandas, polars, pyarrow, numpy, dict-of-columns, and list-of-records inputs are all accepted without conversion.
Features
- Polyharmonic / Duchon smooths combine magnitude, gradient, and curvature penalty operators on the same basis. P-spline and thin-plate smooths use their standard derivative penalties. Each penalized block has its own smoothing parameter.
- Flexible link functions:
flexible(base)adds a spline offset on a base link;blended(...)learns a mixture weight;sasandbeta-logisticlearn shape parameters. - Surface smooths in arbitrary dimension: thin-plate, Duchon (scale-free
by default, hybrid with
length_scale=...), and Matérn, with automatic knot placement. - Tensor-product and manifold smooths:
te(...)/ti(...)B-spline tensors, periodic 1-D, cylinder / torus tensor products, intrinsic sphere (Wahba kernel or spherical harmonics), and boundary-conditioned B-splines. - Dispersion GAMLSS for Gamma, Beta, negative-binomial, and Tweedie via
noise_formula=. - Per-axis anisotropy inside a single joint smooth.
- Shape-constrained smooths:
s(x, shape=monotone_increasing),convex,concave. - Difference smooths:
by=factor smooths plus covariance-awaremodel.difference_smooth(...)contrasts with optional simultaneous bands. - Marginal-slope models that separate baseline risk from a calibrated score's effect, for Bernoulli and survival outcomes.
- Survival in several likelihood modes (transformation, Weibull, location-scale, marginal-slope, latent-Gaussian frailty) plus competing-risks cumulative-incidence functions.
- Response geometry for spherical and compositional outcomes via Fréchet-mean tangent-space GAMs.
- Posterior sampling via NUTS where supported, Gaussian Laplace
otherwise, behind one API; conformal prediction intervals via
interval="conformal".
API examples
import gamfit
from gamfit.sklearn import GAMRegressor, GAMClassifier
# Validate before you fit
gamfit.validate_formula(train, "y ~ s(x) + group(site)")
# Posterior sampling and mean bands
posterior = model.sample(train, seed=42)
bands = posterior.predict(test, level=0.95)
# Survival
gamfit.fit(df,
"Surv(entry, exit, event) ~ s(age) + bmi + timewiggle(internal_knots=6)",
survival_likelihood="transformation",
baseline_target="weibull",
)
# scikit-learn
est = GAMRegressor(formula="y ~ s(x)")
est.fit(X, y)
# Diagnose, plot, report
model.diagnose(train).metrics
model.plot(train, x="x", kind="prediction")
model.report("report.html")
Public API
| Symbol | Purpose |
|---|---|
gamfit.fit(data, formula, **kwargs) |
Fit a model. |
gamfit.load(path) / gamfit.loads(bytes) |
Reload a saved model. |
gamfit.load_posterior(path) |
Reload a PosteriorSamples archive. |
gamfit.validate_formula(data, formula, ...) |
Type-check a formula without fitting. |
gamfit.build_info() |
Native extension build metadata. |
gamfit.cuda_diagnostics() / gamfit.format_cuda_diagnostics() |
CUDA probe results. |
gamfit.explain_error(exc) |
Human-readable hint for a gamfit exception. |
gamfit.Model |
Fitted model: predict, summary, check, diagnose, plot, report, sample, save. |
gamfit.SurvivalPrediction |
Per-row hazard / survival surface. |
gamfit.CompetingRisksPrediction, competing_risks_cif |
Competing-risks CIF evaluation. |
gamfit.MultinomialModel |
Multinomial-logit / softmax model. |
gamfit.SamplingConfig, PosteriorSamples, PosteriorPredictive, PairedPosteriorSamples |
Posterior interface. |
gamfit.ResponseGeometryModel, sphere_frechet_mean, simplex_frechet_mean, alr, clr, closure |
Response-geometry utilities. |
gamfit.smooth.Duchon, Matern, BSpline, TensorBSpline, MeasureJet, Sphere |
Smooth descriptors for smooths= and torch. |
gamfit.sklearn.GAMRegressor / GAMClassifier |
scikit-learn estimators. |
Full reference: https://gamfit.readthedocs.io/en/latest/api-reference/.
Optional extras
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[cuda]" # NVIDIA CUDA 12 wheel libraries on Linux x86_64
uv add "gamfit[all]" # pandas + plot + sklearn extras
uv add torch # PyTorch bridge dependency
GPU acceleration
CUDA support (cuBLAS / cuSOLVER / cuSPARSE) is built into the same
wheel; there is no separate gamfit-gpu package. Install
gamfit[cuda] on Linux x86_64 when you want PyPI's NVIDIA CUDA 12
runtime libraries instead of a system CUDA toolkit. Per-op dispatch
thresholds are derived at probe time from measured GPU FP64 throughput,
CPU FP64 throughput, and PCIe bandwidth, so small kernels stay on the
CPU. Inspect the calibrated thresholds with
gamfit.build_info()["cuda_diagnostics"] or
gamfit.format_cuda_diagnostics().
The wheel uses the CUDA 12 ABI. If PyTorch has already mapped a complete CUDA stack, gamfit continues that same stack rather than preloading a second system toolkit. Without an existing stack it loads one complete system or packaged NVIDIA stack. The GPU probe refuses a partial or mixed mapped stack because CUDA context and library-handle ownership cannot be safely split across implementations.
License
AGPL-3.0-or-later. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for gamfit 0.1.263
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| gamfit-0.1.263.tar.gz | 18.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| gamfit-0.1.263-cp310-abi3-manylinux_2_31_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.31+ x86-64 | Details |
Total release size: 51.2 MB
Release files / gamfit-0.1.263.tar.gz
| Download URL | gamfit-0.1.263.tar.gz |
|---|---|
| Size | 18.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
303b24c4d6e7be5143037d3e9ca6703f92c03feadb322e883b85c78427c6ee7c
|
|
BLAKE2b-256 checksum How to use checksums |
7492b9f4282036a53a6da0ec2ea2e6220af8980dc63c847c3c65b2120c6ba986
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / gamfit-0.1.263-cp310-abi3-manylinux_2_31_x86_64.whl
| Download URL | gamfit-0.1.263-cp310-abi3-manylinux_2_31_x86_64.whl |
|---|---|
| Size | 33.2 MB |
| Tags | CPython 3.10 Linux glibc 2.31+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
fdf5e64420629ea859bcb4beb6b43f5ee1ced502c3ec5750ff85c6158a23209d
|
|
BLAKE2b-256 checksum How to use checksums |
c35d0afabc124215715af251b04f159a4236f60f8ade9272ddae41ed97c70fd4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
