Cookbook

The Whittaker Cookbook is filled with short and self-contained recipes that try to answer one question at a time. Every recipe is fully executable so you can copy the code and run it easily in your own environment.

Getting started

Start here if you are new to Whittaker. These recipes cover the core workflow: fitting a model, picking the right response distribution, and reading the output.

Fit Your First Smooth

Go from raw data to a fitted GAM and a model summary in five lines.

Choose a Response Family

Pick the right distribution for your outcome variable: Gaussian, Poisson, Binomial, and more.

Read the Model Summary

Understand EDF, significance tests, and fit statistics at a glance.

Smooth terms

The smooth term (its basis type, basis dimension, and interaction structure) is the main modeling decision in a GAM. These recipes cover the most useful smooth types and how to configure them.

Fit a Thin Plate Regression Spline

Understand the default smooth basis and when to use it.

Control Basis Dimension with k

Choose k large enough to avoid underfitting, then let REML handle the rest.

Fit a Cyclic Smooth to Seasonal Data

Use bs=‘cc’ to model a periodic pattern without discontinuities at the boundary.

Add a Tensor Product for Two Predictors

Model the joint nonlinear effect of two predictors, including their interaction, with te().

Use a By-Variable Smooth

Fit a separate smooth curve per group without assuming the groups share the same shape.

Add a Random Effect

Account for repeated-measures clustering with s(group, bs=‘re’).

Fit a Spatial Smooth with a Tensor Product

Use te(x, y) to capture two-dimensional spatial autocorrelation over a geographic field.

Response families

The response family determines the assumed distribution of your outcome and the link function that connects it to the linear predictor. These recipes show how to handle counts, binary outcomes, and proportions (the most common departures from a Gaussian response).

Model Count Data with Poisson

Fit a GAM when the response is a non-negative integer count, such as events per interval.

Model Binary Outcomes with Binomial

Fit a logistic GAM for 0/1 responses. Predictions come back as probabilities.

Model Skewed Positive Data with Gamma

Use the Gamma family for right-skewed continuous responses such as wages, costs, or durations.

Handle Overdispersed Counts with Negative Binomial

Switch from Poisson to NegativeBinomial when residual deviance greatly exceeds residual df.

Model Proportions with Beta

Fit a Beta GAM for responses bounded strictly between 0 and 1, such as rates or fractions.

Estimate a Survival Curve with Cox PH

Model time-to-event data with right censoring using the Cox proportional hazards family.

Prediction and inference

A fitted GAM is most useful when you can generate predictions at new inputs and attach uncertainty estimates. These recipes cover point predictions, standard errors, and several flavors of confidence interval.

Predict on New Data

Generate fitted values for any set of covariate values after fitting (grids, held-out rows, or hypothetical inputs).

Get Confidence Intervals

Add pointwise, simultaneous, or prediction-interval uncertainty bands to any set of predictions.

Get Simultaneous Confidence Bands

Get bands that jointly cover the whole fitted curve at 95%, not just each point in isolation.

Get Prediction Intervals

Bound individual future observations, not just the conditional mean, with prediction intervals.

Extract Term-Level Contributions

Decompose a prediction into each smooth’s individual contribution to the linear predictor.

Predict on the Link Scale

Get linear predictor values instead of back-transformed response-scale predictions.

Diagnostics and model selection

Before trusting a model’s predictions you should verify that it is well-specified. These recipes walk through basis dimension checks, residual analysis, and how to choose a smoothness selection criterion.

Check Basis Dimension Adequacy

Verify that k is large enough to capture the true shape using the k-index diagnostic.

Inspect Residuals

Plot deviance residuals and the QQ plot to spot patterns that signal a poor model fit.

Compare Models with AIC

Rank nested or non-nested models by AIC to balance fit quality against model complexity.

Cross-Validate a GAM

Get an honest out-of-sample estimate of predictive performance using k-fold cross-validation.

Choose a Smoothing Method

Compare REML, GCV, and ML smoothness selection and know when each is the right choice.

Use Select Smoothing to Shrink Away a Term

Add an extra penalty so irrelevant smooth terms can shrink completely to zero during fitting.

Shape constraints

Shape-constrained smooths enforce monotone or convex behavior when domain knowledge demands it. Use them to make a GAM obey known physical constraints while still fitting the data nonparametrically.

Fit a Monotone Increasing Smooth

Constrain a smooth to be non-decreasing with bs=‘mpi’ when the response must rise with the predictor.

Fit a Monotone Decreasing Smooth

Constrain a smooth to be non-increasing with bs=‘mpd’ to model effects that can only fall.

Fit a Convex Smooth

Enforce bowl-shaped curvature with bs=‘cx’ for responses that have a known convex structure.

Data input

Whittaker accepts Pandas DataFrames, Polars DataFrames, PyArrow Tables, plain dicts, and NumPy arrays interchangeably. This section shows how to work with data formats you may already have on hand, including how to account for exposure with an offset term.

Use a Polars DataFrame

Pass a Polars DataFrame directly to fit() without converting to NumPy or pandas first.

Use a PyArrow Table

Pass a PyArrow Table directly to fit(): Narwhals handles the conversion transparently.

Use an Offset Term for Exposure

Model rates instead of raw counts by fixing log(exposure) as an offset in a Poisson formula.

Advanced models

These recipes cover specialized GAM extensions for structured problems: heteroscedastic responses, zero-inflated counts, quantile and conformal inference, causal estimation, multiple correlated responses, functional predictors, and online learning.

Model Location and Scale Together (GAMLSS)

Fit both the mean and variance as smooth functions of covariates using a Gaussian location-scale model.

Model Zero-Inflated Counts

Handle excess zeros with a zero-inflated Poisson model and separate mean and zero-probability smooths.

Fit Quantile Regression

Estimate multiple quantile curves simultaneously using a smooth quantile GAM.

Enforce Non-Crossing Quantiles

Prevent quantile curves from crossing by enabling the isotonic non-crossing constraint.

Build Conformal Prediction Intervals

Construct distribution-free prediction intervals with guaranteed coverage using split conformal prediction.

Estimate an Average Treatment Effect

Use a partially linear GAM to estimate a causal ATE while controlling for confounders nonparametrically.

Estimate Heterogeneous Treatment Effects (CATE)

Estimate how treatment effects vary with individual characteristics using an interactive causal GAM.

Fit a Multi-Response GAM

Model multiple correlated responses simultaneously with a shared covariate structure.

Fit a Functional Covariate

Model how a scalar response depends on an entire observed curve using a functional GAM.

Update a Streaming GAM Incrementally

Fit a GAM online by calling partial_fit() on successive data batches, then solve() to update the model.

Large datasets

When data is too large to hold in memory, these approaches fit the same smooth models without materializing the full design matrix (using discretization, DuckDB, or Polars streaming).

Fit a BigGAM on a Large DataFrame

Use BigGAM to fit a smooth model on millions of rows without materializing the full design matrix.

Query with DuckDB and Fit In-Database

Fit a GAM directly on data held in DuckDB without loading it into Python memory.

Stream a Polars LazyFrame

Fit a GAM on a Polars LazyFrame, deferring data loading until fit time.

Deployment

Once a model is fit, you will often need to persist it, share it, or work with it in an existing ML pipeline. These recipes cover serialization, scikit-learn compatibility, and R interoperability.

Save and Load a Fitted Model

Persist a fitted model to disk with save_gam() and restore it for inference with load_gam().

Use a GAM in a scikit-learn Pipeline

Wrap a GAM in a Pipeline for cross-validation and grid search using the sklearn-compatible estimators.

Export a Model to R’s mgcv Format

Convert a fitted whittaker GAM to an mgcv-compatible dict for cross-language interoperability with R.