API Reference

Core model

The primary GAM interface for fitting, predicting, and inspecting models.

GAM: Generalized Additive Model with automatic smoothness selection.
PredictionResult: Container returned by GAM.predict() for type="response" or type="link".
TermsPredictionResult: Container returned by GAM.predict(type="terms").
PosteriorPredictResult: Container returned by GAM.posterior_predict().
GoodnessOfFit: Goodness-of-fit statistics returned by GAM.goodness_of_fit().
GamCheckResult: Container returned by GAM.gam_check(), bundling residual diagnostics with fit summary
CheckDataResult: Structured diagnostic data underlying check() plots.
SensitivityResult: Result of a smoothing-parameter sensitivity analysis.
PartialDependenceResult: Partial dependence data for one smooth term.
SimultaneousCIResult: Simultaneous confidence band for a smooth term.

Inference

Result types from parametric and smooth tests, concurvity, influence diagnostics, derivatives, marginal effects, and contrasts.

ParametricTestResult: Result of a Wald test for a parametric coefficient.
SmoothTestResult: Result of an approximate test for H_0: f_j = 0.
ConcurvityResult: Concurvity diagnostics for smooth terms.
KCheckResult: Result of basis dimension adequacy check for a single smooth.
InfluenceResult: Observation-level influence diagnostics.
DispersionTestResult: Result of a dispersion test.
VIFResult: Variance inflation factor for a parametric term.
DerivativeResult: Result of smooth derivative estimation.
MarginalEffectResult: Result of marginal effect estimation for one smooth term.
ContrastResult: Result of a pairwise comparison between two conditions.

Formula

Formula parsing and term specifications for model construction.

Formula: A parsed model formula: the structured representation of a GAM’s right-hand side.
SmoothTerm: A smooth term, e.g. s(x1, bs='cr', k=10) or te(x1, x2).
LinearTerm: A plain linear (parametric) term, e.g. x1 or group.
InteractionTerm: A two-way parametric interaction between two bare covariates, e.g. x1 * x2.
OffsetTerm: An offset term, e.g. offset(log_exposure).
parse_formula(): Parse formula into a ~whittaker.formula.terms.Formula.

Response families

Distributions and link functions for the response variable. Each family specifies a conditional distribution and a link function relating the linear predictor to the conditional mean.

Family: Abstract family defining the response distribution and link function.
Gaussian: Gaussian (Normal) family with identity link.
Poisson: Poisson family with log (canonical) link.
Binomial: Binomial family with logit (canonical) link.
Gamma: Gamma family with log link.
NegativeBinomial: Negative Binomial family with log link (NB2 parameterization).
Beta: Beta regression family with logit link.
Tweedie: Tweedie family with log link.
TweedieEstimated: Tweedie family with variance power estimated by profile likelihood.
tw(): Create a Tweedie family with estimated variance power.
InverseGaussian: Inverse Gaussian family with log link.
CoxPH: Cox proportional hazards family for survival analysis.
OrderedCategorical: Ordered categorical (proportional odds / cumulative logit) family.
Multinomial: Multinomial logistic family for unordered categorical responses.

Distributional families (GAMLSS)

Location-scale-shape families for distributional regression, where multiple distribution parameters are modeled as smooth functions.

GAMLSSFamily: Abstract base class for GAMLSS distributional families.
GaussianLS: Gaussian location-scale family for GAMLSS.
GammaLS: Gamma location-scale family for GAMLSS.
BetaLS: Beta family for GAMLSS with mean-precision parameterisation.
ZeroInflatedPoisson: Zero-inflated Poisson (ZIP) family for GAMLSS.
ZeroInflatedNegativeBinomial: Zero-inflated negative binomial (ZINB) family for GAMLSS.

Distributional regression

The GAMLSS fitting interface for distributional regression models.

GAMLSS: Generalized Additive Model for Location, Scale, and Shape.
GAMLSSPrediction: Result of GAMLSS.predict().

Smooth basis types

Basis constructors for smooth terms. Each basis type can be specified in a formula via bs= or constructed directly for advanced use.

SmoothBasis: Abstract base class for all smooth basis types.
TPRS: Thin Plate Regression Splines (TPRS).
CRS: Cubic Regression Splines (natural cubic splines with quantile knots).
PSpline: P-Spline: B-spline basis with m-th order difference penalty.
CyclicCRS: Cyclic Cubic Regression Spline (periodic natural cubic spline).
CyclicPSpline: Cyclic P-Spline (periodic B-spline basis with circular difference penalty).
ShrinkageTPRS: Shrinkage Thin Plate Regression Spline.
ShrinkageCRS: Shrinkage Cubic Regression Spline.
DuchonSpline: Duchon spline basis.
GaussianProcess: Gaussian process (kriging) smooth basis.
SoapFilm: Soap film smooth for 2-D domains with complex boundaries.
MRFBasis: Markov random field basis for areal spatial data.
AdaptiveTPRS: Adaptive Thin Plate Regression Spline.
RandomEffectBasis: Random effect basis (one-hot encoding with identity penalty).
FactorSmoothBasis: Factor-smooth interaction basis (per-level smooth with shared penalties).
TensorProductBasis: Tensor product of marginal smooth bases (te()-style interaction smooth).
TensorInteractionBasis: Tensor product interaction basis (ti()-style pure interaction smooth).
TensorProductBasisT2: Tensor product basis with full penalty decomposition (t2()-style interaction smooth).

Shape-constrained smooths

Monotone, convex, and concave smooth basis types with built-in shape enforcement.

MonotonePSpline: Shape-constrained P-spline: monotone increasing or decreasing.
ConvexPSpline: Shape-constrained P-spline: convex or concave.

Quantile regression

Quantile GAMs with optional non-crossing constraints.

QuantileGAM: Non-crossing quantile GAM.
QuantileGAMResult: Result container for a fitted QuantileGAM.
QuantileFamily: Quantile regression via the Extended Log-F (ELF) pseudo-family.
calibrate_sigma(): Find the ELF bandwidth sigma that minimises out-of-sample ELF loss.

Conformal prediction

Distribution-free prediction intervals via split, CV+, and jackknife+ conformal methods.

conformal_fit(): Fit a GAM with conformal calibration.
conformal_coverage(): Compute empirical coverage of conformal intervals on held-out data.
ConformalPredictor: A calibrated conformal predictor ready to produce intervals.
ConformalResult: Result of conformal prediction.

Causal inference

Causal GAMs using double/debiased machine learning (DML), heterogeneous treatment effect estimation (CATE), and mediation analysis.

CausalGAM: Causal GAM for treatment effect estimation.
TreatmentEffect: Average treatment effect estimate with inference.
CATEResult: Conditional average treatment effect estimates.
mediation_analysis(): Causal mediation analysis with GAM nuisance models.
MediationResult: Mediation analysis results.

Streaming and online GAMs

Incremental fitting via sufficient statistics for data that arrives in batches.

StreamingGAM: Streaming / online GAM.
StreamingSnapshot: A snapshot of streaming GAM state at a point in time.

Multi-response GAMs

Joint fitting of multiple response variables with optional residual correlation modeling.

MultiResponseGAM: Multi-response GAM.
MultiResponseResult: Prediction result for multiple responses.
ResidualCorrelation: Estimated residual correlation structure.

Functional regression

Scalar-on-function regression where predictors include functional covariates (curves).

FunctionalGAM: Scalar-on-function GAM.
FunctionalTerm: Specification for a functional covariate.
CoefficientFunction: Estimated coefficient function beta(t) for a functional term.

Large datasets

Scalable GAM fitting for datasets that exceed memory or benefit from parallel computation.

BigGAM: GAM for large datasets using discretized fitting.
PolarsGAM: GAM that reads data from Polars LazyFrames, DataFrames, or files.
DuckDBGAM: GAM that reads data directly from DuckDB via SQL.

Cross-validation

K-fold cross-validation for GAMs with deviance, MSE, and MAE scoring.

cross_validate(): K-fold cross-validation for a GAM specification.
CVResult: Result of cross_validate().

scikit-learn integration

GAM estimators compatible with the scikit-learn API for use in pipelines and grid search.

GAMRegressor: Scikit-learn compatible GAM regressor.
GAMClassifier: Scikit-learn compatible GAM classifier (binary).

Serialization

Save and load fitted GAMs, and convert to/from mgcv-compatible dictionaries.

save_gam(): Save a fitted GAM to a .npz archive.
load_gam(): Load a fitted GAM from a .npz archive created by save_gam.
from_mgcv_dict(): Import an mgcv gam object exported as a dictionary.
to_mgcv_dict(): Export a fitted GAM as an mgcv-compatible dictionary.

Datasets

Built-in synthetic datasets for testing and examples.

load_dataset(): Load a built-in example dataset.
list_datasets(): Return a list of all built-in datasets with their metadata.

Model comparison

Compare fitted GAMs by information criteria, LOO-CV, WAIC, and stacking weights.

compare(): Compare multiple fitted GAMs in a summary table.
ComparisonResult: Result of comparing multiple fitted GAMs.
ComparisonRow: One row of a model comparison table.
loo_compare(): Compare two PSIS-LOO results computed on the same observations.
LOOResult: Result of PSIS-LOO cross-validation on a fitted GAM.
LOOComparison: Comparison of two PSIS-LOO results on the same data.
waic_compare(): Compare two WAIC results computed on the same observations.
WAICResult: Result of WAIC computation on a fitted GAM.
WAICComparison: Comparison of two WAIC results on the same data.
stacking(): Compute stacking weights for model averaging.
StackingResult: Result of stacking weight optimization.

Posterior predictive checks

Simulate data from the posterior predictive distribution to assess model fit.

PPCResult: Result of a posterior predictive check on a fitted GAM.

Plotting

Diagnostic and partial-effect plotting functions.

check(): Produce GAM diagnostic plots.
partial_effects(): Plot partial effects with confidence bands for each smooth term.

Model matrix

Low-level model matrix construction from formulas and data.

build_model_matrix(): Assemble the full design matrix and penalty structure from a formula.
predict_matrix(): Build the prediction design matrix for new data.
ModelMatrix: Numeric design matrix, penalties, and metadata produced by :func:build_model_matrix.
SmoothInfo: Metadata describing where one smooth term lives inside a ModelMatrix.