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

``` bash
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:

``` bash
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.


``` python
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](understanding-gams.md)**: what GAMs are, when to use them, and how they relate to linear models.
- **[Quick start](quick-start.md)**: a complete example from raw data to a fitted model.
- **[Built-in datasets](datasets.md)**: ready-made datasets for learning and testing.

**Fitting models**

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

**Prediction and inference**

- **[Prediction](prediction.md)**: point estimates, standard errors, and confidence bands.
- **[Simultaneous confidence bands](simultaneous-ci.md)**: curve-wide intervals that cover the entire smooth at once.
- **[Partial dependence as data](partial-dependence.md)**: structured arrays for custom plotting or downstream analysis.

**Model diagnostics**

- **[Diagnostics](diagnostics.md)**: basis adequacy, residuals, and QQ plots.
- **[Diagnostic data for custom plots](check-data.md)**: raw diagnostic arrays for matplotlib or other plotting libraries.
- **[Advanced diagnostics](advanced-diagnostics.md)**: influence, concurvity, dispersion tests, and quantile residuals.

**Model selection**

- **[Cross-validation](cross-validation.md)**: K-fold cross-validation for GAMs.
- **[Model comparison](compare.md)**: comparing models with AIC, BIC, and deviance tests.
- **[ANOVA for GAMs](anova.md)**: analysis of deviance for nested model comparisons.

**Extended features**

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

**Large datasets**

- **[Large datasets](large-datasets.md)**: BigGAM, PolarsGAM, and DuckDBGAM.

**Bayesian inference**

- **[Variational inference](variational-inference.md)**: fast approximate Bayesian fitting.
- **[MCMC sampling](mcmc.md)**: full posterior sampling with NUTS and HMC.
- **[LOO comparison](loo.md)**: leave-one-out cross-validation for Bayesian models.
- **[WAIC comparison](waic.md)**: information-criterion-based model comparison.
- **[Posterior predictive checks](ppc.md)**: testing whether the model generates realistic data.
- **[Posterior predictive distributions](posterior-predict.md)**: drawing from the predictive distribution.
- **[Model averaging with stacking](stacking.md)**: combining Bayesian models by stacking weights.

**Advanced inference**

- **[Smoothing parameter sensitivity](sensitivity.md)**: how robust are conclusions to smoothing choices.
- **[Derivatives and marginal effects](derivatives.md)**: rates of change and their uncertainty.

**Tooling**

- **[Programmatic formulas](programmatic-formulas.md)**: building formulas in code.
- **[scikit-learn integration](sklearn.md)**: using Whittaker in ML pipelines.
- **[Model matrix utilities](model-matrix.md)**: inspecting and manipulating design matrices.

**Deployment**

- **[Serialization](serialization.md)**: saving and loading fitted models.