# 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.