pyGAM Documentation

The pyGAM API is organized into several core modules that handle different aspects of Generalized Additive Models (GAMs). To build or extend models, you will primarily interact with these modules:

• pygam.pygam: The main entry point containing the GAM class for model fitting and prediction.
• pygam.terms: Defines the basis functions and terms (e.g., splines) used to model relationships between features and the target.
• pygam.distributions: Contains the error distributions (e.g., Normal, Poisson, Binomial) for the response variable.
• pygam.links: Provides link functions to connect the linear predictor to the mean of the distribution.
• pygam.penalties: Defines the penalty functions used for regularization (smoothing).
• pygam.callbacks: Provides mechanisms for monitoring or modifying the fitting process during optimization.

Generalized Additive Models (GAMs) are smooth semi-parametric models that extend generalized linear models. They take the form:

$$g\left(\mathbb{E}[y|X]\right)=\beta_0+f_1(X_1)+f_2(X_2)+\dots+f_p(X_p)$$

Where:

• $X = [X_1, X_2, ..., X_p]$ are independent variables.
• $y$ is the dependent variable.
• $g$ is a link function relating predictors to the expected value of $y$.
• $f_i$ are feature functions built using penalized B-splines, which allow for automatic modeling of non-linear relationships without manual transformations.

Key Benefits:

• Interpretability: Because the model is additive, you can examine the effect of each $X_i$ on $y$ individually while holding other predictors constant.
• Flexibility: They can model non-linear relationships while maintaining additivity.
• Control: It is easy to incorporate prior knowledge and control for overfitting.

To install the pyGAM package, use the standard pip installation command:

pip install pygam

Since most pyGAM computations are linear algebra operations, you can speed up optimization on large models with constraints by using intel MKL.

An alternative way to ensure NumPy and SciPy are linked to MKL routines is to use the urob.github.io/numpy-mkl third-party build:

pip install numpy scipy --extra-index-url https://urob.github.io/numpy-mkl

To install the latest development version, clone the repository and use pip.

• For an unstable "latest" development version, use pip install ..
• For an editable version (useful for contributors), use pip install -e ..

# Clone the repo, cd into the main directory, then:
pip install .  # for an unstable "latest" dev version
pip install -e .  # for an editable developer/contributor version

You can install pyGAM using the conda-forge channel. Note that the Conda version may be less up-to-date than the PyPI version.

conda install -c conda-forge pyGAM

To contribute to pyGAM, follow these steps to set up an editable installation with developer dependencies in a new Python environment:

1. Upgrade pip:

   pip install --upgrade pip

2. Install the package in editable mode with dev dependencies:

   pip install -e ".[dev]"

3. Run tests using pytest:

   py.test -s

Since most pyGAM computations involve linear algebra, you can speed up optimization on large models with constraints by using a version of NumPy and SciPy linked to Intel MKL routines.

Because managing MKL-linked NumPy via Conda can be complex, an alternative is to use a third-party build:

pip install numpy scipy --extra-index-url https://urob.github.io/numpy-mkl

pyGAM provides shorthand functions to quickly instantiate common term types for your model. These functions are often used to build the additive components of a Generalized Additive Model.

• l(feature, ...): Creates a LinearTerm.
• s(feature, ...): Creates a SplineTerm (for non-linear smooths).
• f(feature, ...): Creates a FactorTerm (for categorical variables).
• te(*args, ...): Creates a TensorTerm (for interaction terms).
• intercept: A special instance of Intercept to include a constant term.

from pygam import l, s, f, te, intercept

# Example of building a model specification
model_terms = intercept + l(0) + s(1) + f(2) + te(3, 4)

In pyGAM, Link objects are used to connect the linear predictor (lp) to the mean (mu) of a distribution. This is a core component of Generalized Linear Models (GLMs).

Each link class implements three primary methods:

• link(mu, dist): The GLM link function. It transforms the mean mu into the linear prediction lp.
• mu(lp, dist): The inverse link function (mean function). It transforms the linear prediction lp back into the mean mu.
• gradient(mu, dist): The derivative of the link function with respect to mu.

Note: Some link functions (like LogitLink) require a dist (Distribution) instance that provides a levels attribute to define the bounds of the mean.

The gridsearch method allows you to find optimal smoothing parameters (like lam) by evaluating a grid of values against an objective metric.

Parameters:

• X, y: Input data.
• objective: Metric to optimize. Options: ['AIC', 'AICc', 'GCV', 'UBRE', 'auto']. If 'auto', it uses GCV for unknown scale and UBRE for known scale.
• return_scores: If True, returns a dictionary of {fitted_model: score}.
• keep_best: If True, the model instance is updated to the best found model.
• **kwargs: Pairs of parameters and iterables (e.g., lam=[1e-3, 1, 1e3]).

Warning: It is not recommended to search over a grid that alternates between known and unknown scales, as scores will not be comparable.

gam.gridsearch(X, y, lam=[0.1, 1.0, 10.0], objective='GCV')

pyGAM provides several distribution classes to define the response variable's distribution in a model. These classes implement the necessary statistical properties like variance functions (V), deviance, and log-likelihood (log_pdf).

Available distributions include:

• NormalDist: For Gaussian linear models.
• BinomialDist: For binomial/Bernoulli models (requires levels parameter).
• PoissonDist: For count data.
• GammaDist: For positive continuous data.
• InvGaussDist: For Inverse Gaussian (Wald) distributions.

All distributions inherit from the Distribution base class and can be instantiated with an optional scale parameter.

from pygam.distributions import NormalDist, BinomialDist

# For a standard normal distribution
dist = NormalDist(scale=1.0)

# For a binomial distribution with 10 trials per observation
dist = BinomialDist(levels=10)