Get started

Whittaker brings the full power of Generalized Additive Models (GAMs) to Python. It is built on NumPy and SciPy, follows the mathematical framework of Wood’s mgcv, and provides a formula-based interface that makes specifying even complex models a one-liner.

Installation

Whittaker targets Python 3.10+ and is not yet on PyPI. Once released:

pip install whittaker

Dependencies

The core package depends on:

Package	Purpose
NumPy	Array computation and linear algebra
SciPy	Cholesky factorization, optimization, B-spline evaluation

These are installed automatically.

From source

To install the development version from GitHub:

git clone https://github.com/rich-iannone/whittaker.git
cd whittaker
pip install -e ".[dev]"

The [dev] extra installs testing and linting tools (pytest, ruff, pyright).

Verifying the installation

After installing, check that Whittaker loads correctly and prints its version.

import whittaker as wk

# Print the installed version
print(wk.__version__)

0.1.dev390+g931406871.d20260812

If no error is raised and a version string appears, the installation is working.

What Whittaker provides

Whittaker includes a broad set of tools for modern statistical modeling:

• 14 response families including Gaussian, Poisson, Binomial, Gamma, Negative Binomial, Beta, Tweedie, Inverse Gaussian, Cox PH, and more
• 20+ smooth basis types including thin plate regression splines (TPRS), P-splines, cubic regression splines, tensor products, cyclic splines, random effects, soap film smooths, Gaussian processes, and Markov random fields
• Shape constraints: monotone increasing/decreasing, convex, and concave smooths
• Distributional regression (GAMLSS): model location, scale, and shape parameters simultaneously
• Quantile regression with non-crossing constraints
• Conformal prediction for distribution-free prediction intervals
• Causal inference via double/debiased machine learning
• Streaming/online fitting for data that arrives in batches
• Multi-response GAMs for jointly modeling multiple outcomes
• Functional regression for scalar-on-function models
• Large dataset support via BigGAM, PolarsGAM, and DuckDBGAM
• scikit-learn integration for use in ML pipelines

How this guide is organized

The user guide is grouped into sections that follow the modeling workflow.

Getting started

• Understanding GAMs: what GAMs are, when to use them, and how they relate to linear models.
• Quick start: a complete example from raw data to a fitted model.
• Built-in datasets: ready-made datasets for learning and testing.

Fitting models

• Smooth terms: the full catalog of basis types and how to choose among them.
• Response families: Gaussian, Poisson, Binomial, and more.
• Model fitting: the P-IRLS algorithm, smoothness selection, and convergence.
• Data input: how Whittaker accepts dict-based data.

Prediction and inference

• Prediction: point estimates, standard errors, and confidence bands.
• Simultaneous confidence bands: curve-wide intervals that cover the entire smooth at once.
• Partial dependence as data: structured arrays for custom plotting or downstream analysis.

Model diagnostics

• Diagnostics: basis adequacy, residuals, and QQ plots.
• Diagnostic data for custom plots: raw diagnostic arrays for matplotlib or other plotting libraries.
• Advanced diagnostics: influence, concurvity, dispersion tests, and quantile residuals.

Model selection

• Cross-validation: K-fold cross-validation for GAMs.
• Model comparison: comparing models with AIC, BIC, and deviance tests.
• ANOVA for GAMs: analysis of deviance for nested model comparisons.

Extended features

• Shape constraints: monotone, convex, and concave smooths.
• Distributional regression: GAMLSS for location-scale-shape models.
• Quantile regression: quantile GAMs with non-crossing constraints.
• Conformal prediction: distribution-free prediction intervals.
• Causal inference: causal GAMs via double machine learning.
• Streaming and online fitting: incremental GAM fitting.
• Multi-response models: jointly modeling multiple outcomes.
• Functional regression: scalar-on-function regression.

Large datasets

• Large datasets: BigGAM, PolarsGAM, and DuckDBGAM.

Bayesian inference

• Variational inference: fast approximate Bayesian fitting.
• MCMC sampling: full posterior sampling with NUTS and HMC.
• LOO comparison: leave-one-out cross-validation for Bayesian models.
• WAIC comparison: information-criterion-based model comparison.
• Posterior predictive checks: testing whether the model generates realistic data.
• Posterior predictive distributions: drawing from the predictive distribution.
• Model averaging with stacking: combining Bayesian models by stacking weights.

Advanced inference

• Smoothing parameter sensitivity: how robust are conclusions to smoothing choices.
• Derivatives and marginal effects: rates of change and their uncertainty.

Tooling

• Programmatic formulas: building formulas in code.
• scikit-learn integration: using Whittaker in ML pipelines.
• Model matrix utilities: inspecting and manipulating design matrices.

Deployment

• Serialization: saving and loading fitted models.