### Install pyGAM using pip

Source: https://github.com/dswah/pygam/blob/main/docs/index.rst

Install pyGAM from PyPI using pip.

```bash
pip install pygam
```

--------------------------------

### Install bleeding-edge pyGAM from GitHub

Source: https://github.com/dswah/pygam/blob/main/docs/index.rst

Install the latest development version of pyGAM directly from its GitHub repository.

```bash
pip install .
```

```bash
pip install -e .
```

--------------------------------

### Install NumPy and SciPy with MKL support

Source: https://github.com/dswah/pygam/blob/main/docs/index.rst

Install NumPy and SciPy linked to Intel MKL for potential performance improvements on large models with constraints. This uses a third-party build.

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

--------------------------------

### Install Bleeding Edge pyGAM from GitHub

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Install the latest development version of pyGAM from its GitHub repository using poetry. This requires cloning the repository first.

```bash
pip install -e .
```

--------------------------------

### Install Pandas and Matplotlib

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Install the pandas and matplotlib libraries, which are often used alongside pyGAM for data manipulation and visualization.

```bash
pip install pandas matplotlib
```

--------------------------------

### Install pyGAM with Developer Dependencies

Source: https://github.com/dswah/pygam/blob/main/README.md

Install pyGAM in editable mode with developer dependencies for contributing to the project.

```bash
pip install --upgrade pip
pip install -e ".[dev]"
```

--------------------------------

### Install pyGAM using Conda

Source: https://github.com/dswah/pygam/blob/main/docs/index.rst

Install pyGAM from conda-forge. Note that this version may be less up-to-date.

```bash
conda install -c conda-forge pyGAM
```

--------------------------------

### Setup Matplotlib for Plotting

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Configure Matplotlib for interactive plotting with a specified figure size. Import matplotlib.pyplot and enable interactive mode.

```python
import matplotlib.pyplot as plt

plt.ion()
plt.rcParams["figure.figsize"] = (12, 8)
```

--------------------------------

### Load Built-in Datasets

Source: https://context7.com/dswah/pygam/llms.txt

Loads ten example datasets provided with pyGAM. Each dataset can be returned as a ready-to-use (X, y) tuple or as a raw Pandas DataFrame. Demonstrates loading and checking shapes/columns.

```python
from pygam.datasets import (
    mcycle,           # LinearGAM  — motorcycle acceleration
    wage,             # LinearGAM  — mid-Atlantic wage data (3 features)
    coal,             # PoissonGAM — coal-mining accident counts
    faithful,         # PoissonGAM — Old Faithful eruption waiting times
    default,          # LogisticGAM — credit card default (3 features)
    trees,            # GammaGAM   — cherry tree volume (2 features)
    cake,             # LinearGAM  — cake breaking angle (3 features)
    hepatitis,        # LinearGAM  — hepatitis A seroprevalence
    head_circumference, # ExpectileGAM — Dutch boys head circumference
    chicago,          # PoissonGAM — Chicago air pollution (4 features)
    toy_classification,  # LogisticGAM — synthetic with irrelevant features
    toy_interaction,     # LinearGAM  — sinusoid × linear interaction
)

X, y = wage()
print(X.shape)  # (3000, 3)
print(y.shape)  # (3000,)

df = wage(return_X_y=False)
print(df.columns.tolist())  # ['year', 'age', 'education', 'wage']

X_toy, y_toy = toy_classification(n=2000)
print(X_toy.shape)  # (2000, 6)
```

--------------------------------

### LinearGAM for Continuous Response

Source: https://context7.com/dswah/pygam/llms.txt

Fit a LinearGAM for continuous response regression. Includes examples for point predictions, confidence intervals for the mean, and prediction intervals for new observations. Also shows how to calculate R².

```python
from pygam import LinearGAM, s
from pygam.datasets import mcycle

X, y = mcycle()

gam = LinearGAM(s(0, n_splines=20)).fit(X, y)

# Point predictions
preds = gam.predict(X)

# 95 % confidence interval for the mean
XX   = gam.generate_X_grid(term=0, n=200)
pdep, confi = gam.partial_dependence(term=0, X=XX, width=0.95)

# 95 % prediction interval for new observations
intervals = gam.prediction_intervals(XX, width=0.95)
# intervals.shape == (200, 2)  — columns are [lower, upper]

print(f"R² (explained deviance): {gam.score(X, y):.3f}")
# e.g., R² (explained deviance): 0.783
```

--------------------------------

### Custom GAM Model

Source: https://context7.com/dswah/pygam/llms.txt

Build a custom GAM with specified terms, distribution, and link function. Fit the model and print explained deviance. Includes examples for prediction and scoring.

```python
import numpy as np
from pygam import GAM, s, l, f, te
from pygam.datasets import wage

X, y = wage()
# Custom GAM: spline on feature 0 (year), spline on feature 1 (age),
# factor term on feature 2 (education category)
gam = GAM(s(0) + s(1) + f(2), distribution='normal', link='identity')
gam.fit(X, y)

print(gam.statistics_['pseudo_r2']['explained_deviance'])
# e.g., 0.293

preds = gam.predict(X)          # array of shape (3000,)
mu    = gam.predict_mu(X)       # same for GAM with identity link
score = gam.score(X, y)         # explained deviance R²
ll    = gam.loglikelihood(X, y) # log-likelihood scalar
```

--------------------------------

### Load Wage Dataset

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Load the 'wage' dataset from pyGAM's built-in datasets module. This dataset is commonly used for regression examples.

```python
from pygam.datasets import wage

X, y = wage()
```

--------------------------------

### Tensor Product Terms (Interactions) in pyGAM

Source: https://context7.com/dswah/pygam/llms.txt

Illustrates the use of tensor product terms (te) to model 2D interactions between features in pyGAM. This is useful when non-linear interactions are expected. The example compares a model without interaction to one with a tensor product term and shows how to generate 3D partial dependence plots.

```python
from pygam import LinearGAM, te
from pygam.datasets import toy_interaction
import numpy as np

X, y = toy_interaction(n=10000)

# Model without interaction — low R²
gam_no  = LinearGAM().fit(X, y)
print(f"No interaction R²: {gam_no.score(X, y):.3f}")   # ~0.00

# Model with tensor-product interaction — high R²
gam_te  = LinearGAM(te(0, 1, n_splines=10)).fit(X, y)
print(f"Tensor product R²: {gam_te.score(X, y):.3f}")   # ~0.99

# 3D partial dependence (meshgrid=True)
Xs = gam_te.generate_X_grid(term=0, n=30, meshgrid=True)  # tuple of 2 grids
pdep = gam_te.partial_dependence(term=0, X=Xs, meshgrid=True)
print(pdep.shape)  # (30, 30)
```

--------------------------------

### GammaGAM for Positive Continuous Response

Source: https://context7.com/dswah/pygam/llms.txt

Fit a GammaGAM for positive, skewed continuous response variables. Includes examples for tensor-product terms, partial dependence plots, and fitting a custom GAM with an inverse link.

```python
from pygam import GammaGAM, s, te
from pygam.datasets import trees

X, y = trees()   # features: Girth, Height; target: Volume

# Tensor-product term captures interaction between girth and height
gam = GammaGAM(te(0, 1)).fit(X, y)

print(f"Explained deviance: {gam.score(X, y):.3f}")
# e.g., Explained deviance: 0.971

XX = gam.generate_X_grid(term=0, n=50)
pdep = gam.partial_dependence(term=0, X=XX)

# Custom inverse-link model if inverse link is preferred
from pygam import GAM
gam_inv = GAM(distribution='gamma', link='inverse').fit(X, y)
```

--------------------------------

### Custom Penalty Functions in pyGAM

Source: https://context7.com/dswah/pygam/llms.txt

Shows how to define and use custom penalty functions for spline terms in pyGAM. The custom penalty function should accept the number of coefficients and the current coefficients, and return a penalty matrix. This example approximates an L1 penalty using diagonal loading.

```python
import numpy as np
from pygam import LinearGAM, s
from pygam.datasets import mcycle

X, y = mcycle()

def my_l1_approx(n, coef):
    """Approximate L1 via diagonal loading (for demonstration)."""
    if coef is None:
        return np.eye(n)
    return np.diag(1.0 / (np.abs(coef) + 1e-4))

gam = LinearGAM(
    s(0, penalties=my_l1_approx, lam=1.0)
).fit(X, y)

print(gam.score(X, y))
```

--------------------------------

### Building a LogisticGAM with Spline and Factor Terms

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Illustrates the construction of a LogisticGAM using a combination of spline (s) and factor (f) terms. Requires pygam.datasets for data.

```python
from pygam import LogisticGAM, f, s
from pygam.datasets import toy_classification

X, y = toy_classification(return_X_y=True, n=5000)

gam = LogisticGAM(s(0) + s(1) + s(2) + s(3) + s(4) + f(5))
gam.fit(X, y)
```

--------------------------------

### Class Methods

Source: https://github.com/dswah/pygam/blob/main/docs/_templates/autosummary/class.rst

This section lists the methods available for the class. Each method is documented with its signature and a brief description.

```APIDOC
## Class Methods

This section lists the methods available for the class. Each method is documented with its signature and a brief description.

### Methods

- `~ClassName.method_name`
- `~ClassName.another_method`

```

--------------------------------

### Visualize Expectile Predictions

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Generate a grid of X values and plot the predicted values from the fitted ExpectileGAM models (0.05, 0.25, 0.50, 0.75, 0.95) against the original data points. This visualization helps to understand the model's predictions across different tail expectations.

```python
XX = gam50.generate_X_grid(term=0, n=500)

plt.scatter(X, y, c="k", alpha=0.2)
plt.plot(XX, gam95.predict(XX), label="0.95")
plt.plot(XX, gam75.predict(XX), label="0.75")
plt.plot(XX, gam50.predict(XX), label="0.50")
plt.plot(XX, gam25.predict(XX), label="0.25")
plt.plot(XX, gam05.predict(XX), label="0.05")
plt.legend()
```

--------------------------------

### Create Custom GAM Model with Gamma Distribution

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Build a custom GAM model using the base GAM class, specifying the 'gamma' distribution and 'log' link function. The model is then fitted using grid search to find optimal smoothing parameters.

```python
from pygam import GAM
from pygam.datasets import trees

X, y = trees(return_X_y=True)

gam = GAM(distribution="gamma", link="log")
gam.gridsearch(X, y)
```

--------------------------------

### Run pyGAM Tests

Source: https://github.com/dswah/pygam/blob/main/README.md

Execute pyGAM's tests from the project's root directory using pytest.

```bash
py.test -s
```

--------------------------------

### Applying Monotonic and Concave Constraints in LinearGAM

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Demonstrates how to apply 'monotonic_inc' and 'concave' constraints to a feature in LinearGAM. Requires matplotlib for plotting.

```python
from pygam import LinearGAM, s
from pygam.datasets import hepatitis

X, y = hepatitis(return_X_y=True)

gam1 = LinearGAM(s(0, constraints="monotonic_inc")).fit(X, y)
gam2 = LinearGAM(s(0, constraints="concave")).fit(X, y)

fig, ax = plt.subplots(1, 2)
ax[0].plot(X, y, label="data")
ax[0].plot(X, gam1.predict(X), label="monotonic fit")
ax[0].legend()

ax[1].plot(X, y, label="data")
ax[1].plot(X, gam2.predict(X), label="concave fit")
ax[1].legend()
```

--------------------------------

### Gridsearching and Visualizing Confidence Intervals in LinearGAM

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Performs a grid search to find optimal parameters for a LinearGAM and visualizes the predicted function with confidence intervals. Requires numpy and matplotlib.

```python
import numpy as np

from pygam import LinearGAM
from pygam.datasets import mcycle

X, y = mcycle()

gam = LinearGAM()
gam.gridsearch(X, y)

XX = gam.generate_X_grid(term=0)

m = X.min()
M = X.max()
XX = np.linspace(m - 10, M + 10, 500)
Xl = np.linspace(m - 10, m, 50)
Xr = np.linspace(M, M + 10, 50)

plt.figure()

plt.plot(XX, gam.predict(XX), "k")
plt.plot(Xl, gam.confidence_intervals(Xl), color="b", ls="--")
plt.plot(Xr, gam.confidence_intervals(Xr), color="b", ls="--")
_ = plt.plot(X, gam.confidence_intervals(X), color="r", ls="--")
```

--------------------------------

### Expectile GAM for Asymmetric/Quantile-like Regression

Source: https://context7.com/dswah/pygam/llms.txt

Fit multiple expectile curves for quantile-like regression. The `fit_quantile` method uses binary search to find the expectile matching a desired quantile.

```python
from pygam import ExpectileGAM, s
from pygam.datasets import head_circumference

X, y = head_circumference()

# Fit multiple expectile curves
XX = None  # will be auto-generated
quantiles = [0.1, 0.5, 0.9]
models = {}
for q in quantiles:
    gam = ExpectileGAM(s(0, n_splines=25), expectile=0.5)
    gam.fit_quantile(X, y, quantile=q, max_iter=30, tol=0.005)
    models[q] = gam

# Generate prediction grid
XX = models[0.5].generate_X_grid(term=0, n=200)
for q, m in models.items():
    pdep = m.partial_dependence(term=0, X=XX)
    print(f"Quantile {q}: range [{pdep.min():.1f}, {pdep.max():.1f}]")
```

--------------------------------

### Gridsearch Linear GAM with Smooth and Factor Terms

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Perform a grid search to find optimal smoothing parameters for a Linear GAM model that includes both smooth (s) and factor (f) terms. Requires importing LinearGAM, s, and f from pygam, and a dataset.

```python
from pygam import LinearGAM, f, s
from pygam.datasets import wage

X, y = wage(return_X_y=True)

## model
gam = LinearGAM(s(0) + s(1) + f(2))
gam.gridsearch(X, y)
```

--------------------------------

### Logging Model Deviance During Optimization

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Demonstrates how to access and plot the 'deviance' callback logs from a fitted GAM, which tracks model deviance during optimization iterations.

```python
_ = plt.plot(gam.logs_["deviance"])
```

--------------------------------

### sample

Source: https://context7.com/dswah/pygam/llms.txt

Simulates draws from the approximate posterior of model coefficients and smoothing parameters, useful for uncertainty quantification.

```APIDOC
## sample

### Description
Simulates draws from the approximate posterior of model coefficients and smoothing parameters; useful for uncertainty quantification.

### Method
`sample(X, y, quantity='y', n_draws=100, n_bootstraps=1)`

### Parameters
- **X** (array-like): Input data.
- **y** (array-like): Target data.
- **quantity** (str, optional): The quantity to draw samples for. Options are 'y' (response), 'mu' (conditional mean), or 'coef' (coefficients). Defaults to 'y'.
- **n_draws** (int, optional): The number of posterior samples to draw. Defaults to 100.
- **n_bootstraps** (int, optional): The number of bootstrap samples to use for estimating the posterior. Defaults to 1.

### Request Example
```python
import numpy as np
from pygam import LinearGAM, s
from pygam.datasets import mcycle

X, y = mcycle()

gam = LinearGAM(s(0)).gridsearch(X, y)

# Draw 200 posterior samples of the response
y_draws = gam.sample(X, y, quantity='y', n_draws=200, n_bootstraps=5)
# y_draws.shape == (200, n_samples)

# Draw posterior samples of the conditional mean mu
mu_draws = gam.sample(X, y, quantity='mu', n_draws=200, n_bootstraps=1)

# Draw posterior samples of coefficients
coef_draws = gam.sample(X, y, quantity='coef', n_draws=200, n_bootstraps=1)
# coef_draws.shape == (200, n_coefs)

# Compute 90% credible band from draws
lower = np.percentile(mu_draws, 5, axis=0)
upper = np.percentile(mu_draws, 95, axis=0)
```

### Response
- **samples** (numpy.ndarray): An array containing the drawn posterior samples. The shape depends on the `quantity` parameter.
```

--------------------------------

### Fit Poisson GAM with Tensor Product Interaction

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Fit a Poisson GAM model including a tensor product interaction term. Requires importing PoissonGAM, s, and te from pygam, and a dataset.

```python
from pygam import PoissonGAM, s, te
from pygam.datasets import chicago

X, y = chicago(return_X_y=True)

gam = PoissonGAM(s(0, n_splines=200) + te(3, 1) + s(2)).fit(X, y)
```

--------------------------------

### Plotting Prediction Intervals with PyGAM

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Visualizes the prediction intervals for a LinearGAM model. Requires pygam, matplotlib, and a dataset like mcycle.

```python
from pygam import LinearGAM
from pygam.datasets import mcycle

X, y = mcycle(return_X_y=True)

gam = LinearGAM(n_splines=25).gridsearch(X, y)
XX = gam.generate_X_grid(term=0, n=500)

plt.plot(XX, gam.predict(XX), "r--")
plt.plot(XX, gam.prediction_intervals(XX, width=0.95), color="b", ls="--")

plt.scatter(X, y, facecolor="gray", edgecolors="none")
plt.title("95% prediction interval");
```

--------------------------------

### Plot 3D Surface of Partial Dependence

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Generate and plot a 3D surface representing the partial dependence of a GAM model. Requires generating an X grid and calculating partial dependence.

```python
XX = gam.generate_X_grid(term=1, meshgrid=True)
Z = gam.partial_dependence(term=1, X=XX, meshgrid=True)

ax = plt.axes(projection="3d")
ax.plot_surface(XX[0], XX[1], Z, cmap="viridis")
```

--------------------------------

### Fit Linear GAM with Spline and Factor Terms

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Fit a LinearGAM model using spline terms for the first two features and a factor term for the third. This requires importing LinearGAM, f, and s from pygam.

```python
from pygam import LinearGAM, f, s

gam = LinearGAM(s(0) + s(1) + f(2)).fit(X, y)
```

--------------------------------

### Define a GAM with Spline and Tensor Product Terms

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Construct a GAM with a Poisson distribution and log link function, specifying a spline on feature 0, a tensor product on features 1 and 3, and a spline on feature 2. Models include an intercept by default.

```python
from pygam import GAM, s, te

GAM(s(0, n_splines=200) + te(3, 1) + s(2), distribution="poisson", link="log")
```

--------------------------------

### Fit Linear GAM with By-Variable Interaction

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Fit a Linear GAM model using a smooth term with a by-variable for simple interactions. Requires importing LinearGAM and s from pygam, and a suitable dataset.

```python
from pygam import LinearGAM, s
from pygam.datasets import toy_interaction

X, y = toy_interaction(return_X_y=True)

gam = LinearGAM(s(0, by=1)).fit(X, y)
gam.summary()
```

--------------------------------

### Sample Posterior and Plot Predictions with PyGAM

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Samples from the posterior distribution of coefficients and plots predictions and intervals. Requires `matplotlib` for plotting.

```python
for response in gam.sample(X, y, quantity="y", n_draws=50, sample_at_X=XX):
    plt.scatter(XX, response, alpha=0.03, color="k")
plt.plot(XX, gam.predict(XX), "r--")
plt.plot(XX, gam.prediction_intervals(XX, width=0.95), color="b", ls="--")
plt.title("draw samples from the posterior of the coefficients")
```

--------------------------------

### Convex and Concave Splines in pyGAM

Source: https://context7.com/dswah/pygam/llms.txt

Demonstrates how to apply convex and concave constraints to spline terms in a LinearGAM model. Multiple constraints can be applied to a single term by passing an iterable of constraint names.

```python
from pygam import LinearGAM, s

# Convex spline
gam_cvx = LinearGAM(s(0, constraints='convex')).fit(X, y)

# Concave spline
gam_ccv = LinearGAM(s(0, constraints='concave')).fit(X, y)

# Multiple constraints on the same term (iterable)
gam_multi = LinearGAM(
    s(0, constraints=['monotonic_inc', 'convex'])
).fit(X, y)
```

--------------------------------

### Print Current Lambda Values

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Displays the current regularization parameter (lambda) values for each term in the GAM model. This is useful for understanding the initial regularization strength.

```python
print(gam.lam)
```

--------------------------------

### Display GAM Model Summary

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Print a detailed summary of the fitted GAM model, including distribution, link function, effective degrees of freedom, log-likelihood, and significance codes for each term.

```python
gam.summary()
```

--------------------------------

### PyGAM Term Constructors (s, l, f, te, intercept)

Source: https://context7.com/dswah/pygam/llms.txt

Compose model formulas using term-building functions like s(), l(), f(), and te(). Terms accept smoothing parameters, shape constraints, and data type hints.

```python
from pygam import LinearGAM, s, l, f, te, intercept
from pygam.datasets import wage

X, y = wage()  # features: year(0), age(1), education(2, categorical)

# s(feature)  — cubic B-spline term
# l(feature)  — linear (no spline) term
# f(feature)  — factor/categorical term
# te(i, j)    — tensor-product interaction of two features
# intercept   — explicit intercept term (added automatically by default)
gam = LinearGAM(
    s(0, n_splines=10, lam=0.5) +       # spline on year
    s(1, n_splines=20, constraints='monotonic_inc') +  # constrained spline on age
    f(2)                                 # factor term for education
).fit(X, y)

gam.summary()
# Prints: distribution, link, n_samples, edof, log-likelihood,
#         AIC, AICc, GCV/UBRE, pseudo-R², and per-term lambda/p-values.

# Periodic spline (for cyclic features like day-of-week)
gam_cyclic = LinearGAM(s(0, basis='cp')).fit(X[:, [0]], y)

# No splines, just linear term
gam_lin = LinearGAM(l(0) + l(1) + f(2)).fit(X, y)
```

--------------------------------

### Visualizing Individual Feature Functions in a GAM

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Shows how to plot the partial dependence of each feature on the target variable for a fitted GAM. Requires matplotlib for plotting.

```python
plt.figure()
for i, term in enumerate(gam.terms):
    if term.isintercept:
        continue
    plt.plot(gam.partial_dependence(term=i))
```

--------------------------------

### summary

Source: https://context7.com/dswah/pygam/llms.txt

Prints a formatted table of model statistics and per-term significance information.

```APIDOC
## summary

### Description
Prints a formatted table of model statistics and per-term significance information.

### Method
`summary()`

### Request Example
```python
from pygam import LogisticGAM, s, f
from pygam.datasets import default

X, y = default()
gam = LogisticGAM(f(0) + s(1) + s(2)).fit(X, y)

gam.summary()
```

### Output
The output is a formatted table containing model diagnostics such as distribution, link function, log likelihood, AIC, and per-term statistics including Lambda, Rank, EDoF, P > x, and significance codes.
```

--------------------------------

### Perform Randomized Search for Lambda Values

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Conducts a randomized search over a pre-defined set of lambda values to find optimal regularization parameters for the LinearGAM model. The summary of the best model found is then displayed.

```python
random_gam = LinearGAM(s(0) + s(1) + f(2)).gridsearch(X, y, lam=lams)
random_gam.summary()
```

--------------------------------

### Built-in Datasets

Source: https://context7.com/dswah/pygam/llms.txt

pyGAM provides several built-in datasets that can be loaded for use in modeling.

```APIDOC
## Built-in Datasets

### Description
pyGAM ships ten example datasets. Each returns a model-ready `(X, y)` tuple or a raw Pandas DataFrame.

### Available Datasets
- `mcycle`: LinearGAM — motorcycle acceleration
- `wage`: LinearGAM — mid-Atlantic wage data (3 features)
- `coal`: PoissonGAM — coal-mining accident counts
- `faithful`: PoissonGAM — Old Faithful eruption waiting times
- `default`: LogisticGAM — credit card default (3 features)
- `trees`: GammaGAM — cherry tree volume (2 features)
- `cake`: LinearGAM — cake breaking angle (3 features)
- `hepatitis`: LinearGAM — hepatitis A seroprevalence
- `head_circumference`: ExpectileGAM — Dutch boys head circumference
- `chicago`: PoissonGAM — Chicago air pollution (4 features)
- `toy_classification`: LogisticGAM — synthetic with irrelevant features
- `toy_interaction`: LinearGAM — sinusoid × linear interaction

### Usage Example
```python
from pygam.datasets import (
    mcycle,
    wage,
    coal,
    faithful,
    default,
    trees,
    cake,
    hepatitis,
    head_circumference,
    chicago,
    toy_classification,
    toy_interaction,
)

X, y = wage()
print(X.shape)  # (3000, 3)
print(y.shape)  # (3000,)

df = wage(return_X_y=False)
print(df.columns.tolist())  # ['year', 'age', 'education', 'wage']

X_toy, y_toy = toy_classification(n=2000)
print(X_toy.shape)  # (2000, 6)
```
```

--------------------------------

### Display Model Diagnostics Table

Source: https://context7.com/dswah/pygam/llms.txt

Prints a formatted table summarizing model statistics, including distribution, link function, log-likelihood, AIC, and per-term significance information (Effective DoF, P-value, significance code).

```python
from pygam import LogisticGAM, s, f
from pygam.datasets import default

X, y = default()
gam = LogisticGAM(f(0) + s(1) + s(2)).fit(X, y)

gam.summary()
# Output (example):
# LogisticGAM                                        Binomial
# ============================...=====================================
# Distribution:           BinomialDist  Effective DoF:            7.6482
# Link Function:             LogitLink  Log Likelihood:         -758.7484
# Number of Samples:             10000  AIC:                    1532.3932
# ...
# Feature Function   Lambda   Rank  EDoF   P > x     Sig. Code
# ========================...=========================================
# f(0)               0.6      4     1.0    4.71e-02  *
# s(1)               0.6      20    3.3    2.38e-16  ***
# s(2)               0.6      20    3.3    3.01e-07  ***
# intercept                   1     1.0    6.04e-28  ***
```

--------------------------------

### Perform Grid Search for Lambda Values

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Tunes the model by performing a grid search over specified lambda values to find the optimal regularization parameters that minimize the GCV score. Requires numpy for logspace and a list of lambda arrays for each term.

```python
import numpy as np

lam = np.logspace(-3, 5, 5)
lams = [lam] * 3

gam.gridsearch(X, y, lam=lams)
gam.summary()
```

--------------------------------

### Posterior Simulation for Uncertainty Quantification

Source: https://context7.com/dswah/pygam/llms.txt

Simulates draws from the approximate posterior distribution of model coefficients and smoothing parameters. Useful for quantifying uncertainty in predictions and model parameters. Can draw samples for response, conditional mean, or coefficients.

```python
import numpy as np
from pygam import LinearGAM, s
from pygam.datasets import mcycle

X, y = mcycle()

gam = LinearGAM(s(0)).gridsearch(X, y)

# Draw 200 posterior samples of the response
y_draws = gam.sample(X, y, quantity='y', n_draws=200, n_bootstraps=5)
# y_draws.shape == (200, n_samples)

# Draw posterior samples of the conditional mean mu
mu_draws = gam.sample(X, y, quantity='mu', n_draws=200, n_bootstraps=1)

# Draw posterior samples of coefficients
coef_draws = gam.sample(X, y, quantity='coef', n_draws=200, n_bootstraps=1)
# coef_draws.shape == (200, n_coefs)

# Compute 90% credible band from draws
lower = np.percentile(mu_draws, 5, axis=0)
upper = np.percentile(mu_draws, 95, axis=0)
```

--------------------------------

### Citation for pyGAM

Source: https://github.com/dswah/pygam/blob/main/README.md

Use this BibTex entry to cite the pyGAM library in your research or work. Ensure proper attribution.

```bibtex
@misc{daniel_serven_2018_1208723,
  author       = {Daniel Servén and
                  Charlie Brummitt},
  title        = {pyGAM: Generalized Additive Models in Python},
  month        = mar,
  year         = 2018,
  doi          = {10.5281/zenodo.1208723},
  url          = {https://doi.org/10.5281/zenodo.1208723}
}
```

--------------------------------

### Automatic Smoothing Parameter Tuning with Grid Search

Source: https://context7.com/dswah/pygam/llms.txt

Optimize smoothing parameters (lam) using grid or randomized search, optimizing GCV or UBRE. Supports diagonal, randomized, and per-term grid searches.

```python
import numpy as np
from pygam import LinearGAM, s
from pygam.datasets import mcycle

X, y = mcycle()

gam = LinearGAM(s(0))

# 1. Diagonal search: 11 shared lam values
gam.gridsearch(X, y, lam=np.logspace(-3, 3, 11))
print(f"Best lam: {gam.terms[0].lam}, GCV: {gam.statistics_['GCV']:.4f}")

# 2. Randomized search over a 2-feature model
X2 = np.c_[X, X**2]
gam2 = LinearGAM(s(0) + s(1))
lam_random = np.exp(np.random.randn(30, 2) * 2)  # 30 random (lam0, lam1) pairs
scores = gam2.gridsearch(X2, y, lam=lam_random, return_scores=True)
best = min(scores, key=scores.get)
print(f"Best GCV: {scores[best]:.4f}")

# 3. Per-term grid (cartesian product)
gam3 = LinearGAM(s(0) + s(1))
gam3.gridsearch(X2, y, lam=[[0.1, 1, 10], [0.01, 0.1, 1]])  # 9 combinations
```

--------------------------------

### Visualize Partial Dependence with LogisticGAM

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Visualizes the partial dependence of features on the target variable for a LogisticGAM model. Requires `matplotlib` for plotting.

```python
from pygam import LogisticGAM, f, s
from pygam.datasets import default

X, y = default(return_X_y=True)

gam = LogisticGAM(f(0) + s(1) + s(2)).gridsearch(X, y)

fig, axs = plt.subplots(1, 3)
titles = ["student", "balance", "income"]

for i, ax in enumerate(axs):
    XX = gam.generate_X_grid(term=i)
    pdep, confi = gam.partial_dependence(term=i, width=0.95)

    ax.plot(XX[:, i], pdep)
    ax.plot(XX[:, i], confi, c="r", ls="--")
    ax.set_title(titles[i])
```

--------------------------------

### Visualize Custom GAM Model Fit

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Plot the true values against the predicted values from the custom GAM model. This helps in visually assessing the quality of the model's fit.

```python
plt.scatter(y, gam.predict(X))
plt.xlabel("true volume")
plt.ylabel("predicted volume")
```

--------------------------------

### Fit Model Coefficients with Optional Weights

Source: https://context7.com/dswah/pygam/llms.txt

Train model coefficients using PIRLS, accepting optional sample weights to down-weight specific observations.

```python
import numpy as np
from pygam import LinearGAM, s
from pygam.datasets import mcycle

X, y = mcycle()
weights = np.ones(len(y))
weights[:10] = 0.5   # down-weight early observations

gam = LinearGAM(s(0))
gam.fit(X, y, weights=weights)

print(gam._is_fitted)    # True
print(gam.coef_.shape)   # (n_coefs,)
print(gam.statistics_.keys())
# dict_keys(['n_samples', 'm_features', 'edof', 'scale', 'cov', 'se',
#            'AIC', 'AICc', 'pseudo_r2', 'GCV', 'UBRE', 'loglikelihood',
#            'deviance', 'p_values', 'edof_per_coef'])
```

--------------------------------

### Plotting Partial Dependence with PyGAM

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Plots the partial dependence of each term in a GAM model, including confidence intervals. Requires matplotlib and pygam.

```python
import matplotlib.pyplot as plt
from pygam import LinearGAM

# Assuming 'gam' is a fitted LinearGAM model and 'titles' is a list of titles
# XX is generated using gam.generate_X_grid(term=i)

plt.figure()
fig, axs = plt.subplots(1, 3)
titles = ["year", "age", "education"]
for i, ax in enumerate(axs):
    XX = gam.generate_X_grid(term=i)
    ax.plot(XX[:, i], gam.partial_dependence(term=i, X=XX))
    ax.plot(
        XX[:, i], gam.partial_dependence(term=i, X=XX, width=0.95)[1], c="r", ls="--"
    )
    if i == 0:
        ax.set_ylim(-30, 30)
    ax.set_title(titles[i])
```

--------------------------------

### Access Model Statistics

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Retrieve a list of all available statistics for a fitted GAM model. These statistics are populated after the model has been fitted.

```python
list(gam.statistics_.keys())
```

--------------------------------

### Fit Linear GAM with Adjusted Spline Flexibility

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Fit a LinearGAM model, adjusting the flexibility of the first spline term by specifying the number of basis functions (n_splines=5). Other terms retain default settings.

```python
gam = LinearGAM(s(0, n_splines=5) + s(1) + f(2)).fit(X, y)
```

--------------------------------

### PoissonGAM for Count Data

Source: https://context7.com/dswah/pygam/llms.txt

Fit a PoissonGAM for count data or rate models. Shows prediction of expected counts, including scaling by exposure, and calculation of log-likelihood with exposure.

```python
from pygam import PoissonGAM, s
from pygam.datasets import coal

X, y = coal()   # X: year midpoints, y: accident counts per bin

gam = PoissonGAM(s(0, n_splines=20)).fit(X, y)

# Predict expected counts
counts = gam.predict(X)                  # count scale
counts_with_exposure = gam.predict(
    X, exposure=np.ones(len(X)) * 2     # scale by exposure factor
)

# Log-likelihood with exposure
ll = gam.loglikelihood(X, y, exposure=None)
print(f"Log-likelihood: {ll:.2f}")
# e.g., Log-likelihood: -342.17
```

--------------------------------

### LogisticGAM for Binary Classification

Source: https://context7.com/dswah/pygam/llms.txt

Fit a LogisticGAM for binary classification. Demonstrates prediction of probabilities and binary labels, accuracy calculation, and obtaining deviance residuals for diagnostics.

```python
from pygam import LogisticGAM, s, f
from pygam.datasets import default

X, y = default()   # features: student, balance, income

gam = LogisticGAM(f(0) + s(1) + s(2)).fit(X, y)

# Probabilities and binary labels
proba  = gam.predict_proba(X)           # float array in [0, 1]
labels = gam.predict(X)                 # bool array (threshold 0.5)
acc    = gam.accuracy(X=X, y=y)
score  = gam.score(X, y)               # same as accuracy for LogisticGAM

print(f"Accuracy: {acc:.3f}")
# e.g., Accuracy: 0.973

# Deviance residuals for diagnostics
dev_resid = gam.deviance_residuals(X, y)
```

--------------------------------

### GAM Object Representation

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

This shows the default representation of a GAM object after it has been initialized with specific terms, distribution, and link function.

```python
Result:
GAM(callbacks=['deviance', 'diffs'], distribution='poisson', 
   fit_intercept=True, link='log', max_iter=100, 
   terms=s(0) + te(3, 1) + s(2), tol=0.0001, verbose=False)
```

--------------------------------

### Inverse Gaussian GAM for Heavy-tailed Positive Response

Source: https://context7.com/dswah/pygam/llms.txt

Use InvGaussGAM for heavy-tailed positive data with a log link. An alternative inverse-squared link can be specified.

```python
from pygam import InvGaussGAM, s, te
from pygam.datasets import trees

X, y = trees()

gam = InvGaussGAM(te(0, 1)).fit(X, y)
preds = gam.predict(X)
print(gam.statistics_['AIC'])
# e.g., 165.8

# Use inverse-squared link if needed
from pygam import GAM
gam2 = GAM(distribution='inv_gauss', link='inv_squared').fit(X, y)
```

--------------------------------

### Generate Randomized Lambda Values for Search

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Generates a set of random lambda values for hyperparameter tuning using a randomized search approach. This method is useful for high-dimensional search spaces.

```python
lams = np.random.rand(100, 3)  # random points on [0, 1], with shape (100, 3)
lams = lams * 6 - 3  # shift values to -3, 3
lams = 10**lams  # transforms values to 1e-3, 1e3
```

--------------------------------

### Apply Monotone Shape Constraints to Splines

Source: https://context7.com/dswah/pygam/llms.txt

Enforces shape constraints on spline terms during GAM model fitting. Supports monotonically increasing or decreasing constraints, implemented via penalty-based quadratic programming.

```python
from pygam import LinearGAM, s
from pygam.datasets import mcycle

X, y = mcycle()

# Monotonically increasing spline
gam_inc = LinearGAM(s(0, constraints='monotonic_inc')).fit(X, y)

# Monotonically decreasing spline
gam_dec = LinearGAM(s(0, constraints='monotonic_dec')).fit(X, y)
```

--------------------------------

### Generate X Grid for 3D Plots

Source: https://context7.com/dswah/pygam/llms.txt

Generates a grid of input values for a specific term in a fitted GAM model, useful for creating partial dependence plots, especially in 3D visualizations. Set meshgrid=False for a flattened array.

```python
from pygam import LinearGAM, s

X, y = mcycle()
gam_te = LinearGAM(s(0) + s(1)).fit(X[:, :2], y)
Xs = gam_te.generate_X_grid(term=0, n=30, meshgrid=False)
pdep_grid = gam_te.partial_dependence(term=0, X=Xs)
```

--------------------------------

### Fit Expectile Models with PyGAM

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Fit multiple ExpectileGAM models for different expectile values (0.05, 0.25, 0.50, 0.75, 0.95). The smoothing parameter 'lam' is determined by cross-validation on the 0.50 expectile model and then applied to the others to ensure consistency and prevent expectile crossing.

```python
from pygam import ExpectileGAM
from pygam.datasets import mcycle

X, y = mcycle(return_X_y=True)

# lets fit the mean model first by CV
gam50 = ExpectileGAM(expectile=0.5).gridsearch(X, y)

# and copy the smoothing to the other models
lam = gam50.lam

# now fit a few more models
gam95 = ExpectileGAM(expectile=0.95, lam=lam).fit(X, y)
gam75 = ExpectileGAM(expectile=0.75, lam=lam).fit(X, y)
gam25 = ExpectileGAM(expectile=0.25, lam=lam).fit(X, y)
gam05 = ExpectileGAM(expectile=0.05, lam=lam).fit(X, y)
```

--------------------------------

### Compare Models Using GCV

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/quick_start.ipynb

Compare two fitted GAM models by checking which one has a lower Generalized Cross-Validation (GCV) score. This is useful for automatic model tuning.

```python
gam.statistics_["GCV"] < random_gam.statistics_["GCV"]
```

--------------------------------

### GAM — Base Generalized Additive Model

Source: https://context7.com/dswah/pygam/llms.txt

The base class for all GAMs. It allows for custom combinations of distribution and link functions, along with term expressions. This is useful when no pre-configured subclass meets the specific modeling needs.

```APIDOC
## GAM — Base Generalized Additive Model

### Description
The base class for all GAMs. Accepts a custom combination of distribution and link function along with a term expression. Useful when no pre-configured subclass matches the modeling need.

### Method Signature
```python
GAM(term_expression, distribution='normal', link='identity', **kwargs)
```

### Parameters
- **term_expression**: A combination of terms (e.g., `s(0) + s(1) + f(2)`).
- **distribution**: The statistical distribution for the model (e.g., 'normal', 'binomial').
- **link**: The link function for the model (e.g., 'identity', 'logit').

### Usage Example
```python
import numpy as np
from pygam import GAM, s, l, f, te
from pygam.datasets import wage

X, y = wage()
# Custom GAM: spline on feature 0 (year), spline on feature 1 (age),
# factor term on feature 2 (education category)
gam = GAM(s(0) + s(1) + f(2), distribution='normal', link='identity')
gam.fit(X, y)

print(gam.statistics_['pseudo_r2']['explained_deviance'])
# e.g., 0.293

preds = gam.predict(X)          # array of shape (3000,)
mu    = gam.predict_mu(X)       # same for GAM with identity link
score  = gam.score(X, y)         # explained deviance R²
ll    = gam.loglikelihood(X, y) # log-likelihood scalar
```

### Methods
- **fit(X, y)**: Fits the GAM model to the data.
- **predict(X)**: Returns point predictions.
- **predict_mu(X)**: Returns predictions on the response scale.
- **score(X, y)**: Returns the explained deviance (R²).
- **loglikelihood(X, y)**: Returns the log-likelihood of the model.

### Attributes
- **statistics_**: Dictionary containing model statistics like pseudo R².
```

--------------------------------

### Histogram Smoothing with PoissonGAM

Source: https://github.com/dswah/pygam/blob/main/docs/notebooks/tour_of_pygam.ipynb

Performs histogram smoothing by modeling counts in bins using a PoissonGAM. Requires `matplotlib` for plotting.

```python
from pygam import PoissonGAM
from pygam.datasets import faithful

X, y = faithful(return_X_y=True)

gam = PoissonGAM().gridsearch(X, y)

plt.hist(faithful(return_X_y=False)("eruptions"), bins=200, color="k")
plt.plot(X, gam.predict(X), color="r")
plt.title(f"Best Lambda: {gam.lam[0][0]:.2f}");
```