--- name: whittaker description: > A next-generation Generalized Additive Model (GAM) library for Python. Use when writing Python code that uses the whittaker package. license: MIT compatibility: Requires Python >=3.10. --- # whittaker A next-generation Generalized Additive Model (GAM) library for Python. ## Installation ```bash pip install whittaker ``` ## API overview ### 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` ## Resources - [Full documentation](https://rich-iannone.github.io/whittaker/) - [llms.txt](llms.txt) — Indexed API reference for LLMs - [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs - [Source code](https://github.com/rich-iannone/whittaker)