Changelog

This changelog is generated automatically from GitHub Releases.

v0.2.0

2026-08-24 · GitHub

Whittaker v0.2.0 is a major step toward full Bayesian inference for GAMs. This release introduces two new fitting methods (Variational Inference for fast approximate posteriors and full MCMC sampling via HMC and NUTS) along with a suite of convergence diagnostics: rank-normalized split R-hat, ESS bulk/tail, divergence counting, and diagonal mass matrix adaptation. A 50-recipe cookbook has also been added as a task-oriented companion to the narrative user guide.

New Features

  • Variational Inference — New method="VI" fitting path approximates the posterior as a full-rank Gaussian q(β) = N(m, LL') by maximizing the ELBO with Adam and Gauss-Hermite quadrature. Works with any supported response family and returns a VIResult with posterior mean and covariance for uncertainty quantification without the cost of full MCMC. (#36)

  • HMC sampler — New method="MCMC" fitting path runs static-trajectory Hamiltonian Monte Carlo with Metropolis accept/reject and dual-averaging step-size adaptation. Chains run in parallel via ProcessPoolExecutor and return a MCMCResult with full posterior draws and convergence diagnostics (R-hat, ESS, acceptance rate). (#37)

  • NUTS sampler — The default sampler="NUTS" replaces HMC’s fixed trajectory length with a self-tuning No-U-Turn Sampler that grows a binary tree until a U-turn is detected, eliminating the need to hand-tune leapfrog steps and giving better posterior exploration with no extra configuration. (#38)

Enhancements

  • Mass matrix adaptation — Warmup now runs a two-phase scheme: the first half collects draws to estimate per-parameter posterior variance, then applies a diagonal mass matrix M = diag(1/Var(β)) for the second half. This rescales leapfrog momentum to match each parameter’s scale, improving acceptance rates for models with variables on very different scales. (#41)

  • Rank-normalized split R-hat — The convergence diagnostic now implements the Vehtari et al. (2021) version: each chain is split in half to catch within-chain non-stationarity, and draws are rank-normalized before computing R-hat, making it robust to heavy-tailed posteriors. ESS bulk and ESS tail are also reported. (#42)

  • Divergence tracking — HMC and NUTS now count transitions where the energy error exceeds the leapfrog threshold, indicating regions of extreme curvature. The count is stored in MCMCResult.n_divergent and shown in summary() with an advisory to raise target_accept or reparameterize. (#39, #40)

Bug Fixes

  • Out-of-memory spikes in BigGAM were fixed. Basis fitting previously ran on the full raw input before discretization; it now runs on the deduplicated unique values only, eliminating the memory spike for large datasets. (#35)

Documentation

  • Added a 50-recipe cookbook covering the full workflow from first smooth through response families, tensor products, shape constraints, causal inference, streaming data sources (Polars, DuckDB, PyArrow), GAMLSS, quantile regression, conformal prediction, sklearn integration, and R/mgcv export. (#34)

v0.1.0

2026-08-13 · GitHub

Whittaker brings next-generation Generalized Additive Models to the Python data ecosystem. It works with whatever dataframe library you use (Pandas, Polars, PyArrow, or any Narwhals-compatible frame), gives you the full smooth catalog from R’s mgcv, and ships with interactive publication-quality plots powered by Altair. From a single smoothing spline to distributional regression, quantile GAMs, and causal inference, everything lives under a unified API with principled REML-based smoothness selection.

Core GAM Fitting

  • GAM class — The central model class supporting penalized regression splines with automatic smoothness selection via REML (default), GCV, ML, or fREML. Provides full summary(), diagnostics, and partial-effect visualization.
  • Formula syntax — R-style formulas like "y ~ s(x1) + s(x2, k=20) + te(x3, x4) + x5" with smooth terms, tensor products, linear terms, interactions, offsets, and by-variable smooths. (#1, #8)
  • REML smoothness selection — Principled smoothing-parameter estimation via restricted maximum likelihood. (#5)
  • ML smoothing parameters — Maximum likelihood as an alternative smoothness-selection criterion. (#30)
  • Double penalty smooth selection — Automatic smooth-term selection by adding a second penalty on the null space. (#26)
  • Observation weights — Full support for user-supplied weights in the fitting process. (#24)
  • Offset support — Log-linear offsets for rate models and exposure adjustment. (#25)

Smooth Basis Types

  • Thin plate regression splines (TPRS) — The default smooth basis, optimal under a thin-plate penalty; supports multi-dimensional smooths. (#2, #31)
  • Cubic regression splines (CRS) — Classic cubic splines with knot-based penalization. (#3)
  • P-splines — B-spline bases with discrete difference penalties for flexible, fast smoothing. (#4)
  • Tensor product smooths (te()) — Smooth interactions of multiple covariates via tensor products with separate penalties per margin. (#6)
  • Tensor product interactions (ti()) — Pure interaction surfaces with main effects removed, for ANOVA-style decompositions. (#13)
  • t2() tensor product smooths — Alternative tensor-product construction with a single penalty, following the t2() convention in mgcv. (#16)
  • Cyclic splines — Periodic variants of CRS and P-splines for modeling cyclical patterns (day of year, angle, etc.). (#17)
  • Shrinkage smooths — TPRS and CRS variants that can shrink smooth terms entirely to zero, enabling automatic term selection. (#18)
  • Random effects — Random intercepts and slopes as penalized smooth terms, seamlessly integrated into the GAM framework. (#20)
  • Factor-smooth interactions — Group-level smooth curves via bs="fs", allowing each factor level to have its own smooth with shared penalization. (#21)
  • Duchon splines — Generalized thin-plate splines for spatial smoothing with flexible derivative penalties.
  • Gaussian processes — GP-based smooth terms with squared-exponential and Matérn covariance kernels.
  • Soap film smooths — Smooth functions over complex domains with boundary constraints.
  • Markov random fields — Spatial smoothing over discrete areal units (e.g., regions, districts).
  • Adaptive TPRS — Locally adaptive thin-plate splines that vary smoothness across the covariate range.
  • Shape-constrained smooths — Monotone increasing/decreasing, convex, and concave P-splines via PAVA projection.

Response Families

  • Gaussian — Standard regression with identity link.
  • Poisson — Count data with log link.
  • Binomial — Binary and proportional outcomes with logit link.
  • Gamma — Positive continuous data with log link, plus AIC/BIC model selection. (#9)
  • Negative Binomial — Overdispersed counts with estimated or fixed theta. (#12)
  • Tweedie — Compound Poisson–Gamma distributions for mixed zero-continuous data, including the tw() helper for automatic power-parameter estimation. (#29)
  • Inverse Gaussian — Heavy-tailed positive continuous data.
  • Beta — Rates and proportions bounded on (0, 1).
  • Cox PH — Cox proportional hazards for survival analysis within the GAM framework.
  • Multinomial — Multi-class classification with shared smooth terms.
  • Ordered categorical — Proportional-odds models for ordinal responses.

Prediction & Inference

  • Prediction modes — predict(type=...) with three modes: response scale, link scale, and term-level contributions. (#22)
  • Confidence and prediction intervals — Pointwise and simultaneous confidence bands, plus prediction intervals with appropriate dispersion. (#23, #32)
  • Unconditional confidence intervals — Intervals that account for smoothing-parameter uncertainty, not just conditional-on-lambda variability. (#32)
  • Posterior simulation — Draws from the approximate posterior of model coefficients for Bayesian-style inference and derived-quantity uncertainty. (#28)
  • Parametric term inference — p-values and confidence intervals for linear/parametric terms, plus deviance explained. (#10)
  • Approximate p-values for smooth terms — Reference-distribution-based tests for each smooth’s contribution to the model. (#7)

Model Diagnostics

  • Residual types — Deviance, Pearson, working, and response residuals for all families. (#11)
  • Basis dimension checking — The model.check() method with k-index tests to flag under-smooth terms. (#27)
  • Concurvity diagnostics — Detection of collinearity among smooth terms via worst-case, observed, and estimated concurvity indices. (#14)
  • Smooth-specific partial effects — Partial-effect plots with confidence bands for each smooth term, with optional rug plots and comparison layouts. (#15)
  • ANOVA model comparison — anova.gam()-style sequential deviance tests for comparing nested GAMs. (#19)
  • Cross-validation — K-fold CV with deviance, MSE, or MAE scoring via cross_validate().
  • AIC / BIC — Information criteria for model selection across families. (#9)

Advanced Models

  • Distributional regression (GAMLSS) — Model location, scale, and shape parameters simultaneously with Gaussian, Gamma, and Beta location-scale families, plus zero-inflated Poisson and Negative Binomial.
  • Quantile regression (QuantileGAM) — Fit conditional quantiles with extended log-F loss, optional non-crossing constraints, and sigma calibration.
  • Conformal prediction (ConformalPredictor) — Distribution-free prediction intervals via split conformal, CV+, and jackknife+ methods.
  • Causal inference (CausalGAM) — Double/debiased machine learning for ATE and CATE estimation, with mediation analysis.
  • Streaming GAMs (StreamingGAM) — Incremental fitting via sufficient statistics with exponential decay for tracking distribution shift.
  • Multi-response GAMs (MultiResponseGAM) — Joint fitting of multiple responses with optional residual correlation modeling.
  • Functional regression (FunctionalGAM) — Scalar-on-function regression with B-spline or Fourier bases for functional covariates.

Scalability & Deployment

  • BigGAM — Discretized P-IRLS for fitting GAMs on datasets too large for dense matrix operations.
  • PolarsGAM — Streaming GAM fitting directly from Polars DataFrames or files.
  • DuckDBGAM — SQL-native streaming for GAM fitting against DuckDB databases.
  • Serialization — save_gam() / load_gam() for compact .npz archives, and to_mgcv_dict / from_mgcv_dict for R interoperability.
  • scikit-learn integration — GAMRegressor and GAMClassifier wrappers for use in pipelines, grid search, and cross-validation. (#33)

Dataframe Compatibility

Whittaker is built on Narwhals, so all methods accept and return Pandas DataFrames, Polars DataFrames, PyArrow Tables, or any other Narwhals-compatible frame.

Requirements

  • Python >= 3.10
  • Core dependencies: narwhals>=2.0, numpy>=1.24, scipy>=1.11, typing_extensions>=4.0