GAM — Generalized Additive Models

Generalized Additive Model routines.

aurora.models.gam.fit_gam(x, y, n_basis=10, basis_type='bspline', degree=3, penalty_order=2, lambda_=None, lambda_min=1e-6, lambda_max=1e6, knot_method='quantile', weights=None, use_sparse=False)[source]

Fit univariate Generalized Additive Model using penalized splines.

This function fits a smooth function f(x) to data (x, y) using:

y = f(x) + ε

where f is represented as a linear combination of basis functions with a roughness penalty.

Parameters:

  • x (ndarray, shape (n,)) – Predictor variable.

  • y (ndarray, shape (n,)) – Response variable.

  • n_basis (int, default=10) – Number of basis functions to use.

  • basis_type ({'bspline', 'cubic'}, default='bspline') – Type of spline basis: - ‘bspline’: B-spline basis (local support, partition of unity) - ‘cubic’: Natural cubic spline basis (global support)

  • degree (int, default=3) – Degree of splines (3 for cubic splines).

  • penalty_order (int, default=2) – Order of difference penalty (2 approximates second derivative).

  • lambda (float, optional) – Smoothing parameter. If None, selected automatically via GCV.

  • lambda_min (float, default=1e-6) – Minimum lambda for GCV search.

  • lambda_max (float, default=1e6) – Maximum lambda for GCV search.

  • knot_method ({'quantile', 'uniform'}, default='quantile') – Method for placing knots: - ‘quantile’: Place knots at quantiles of x - ‘uniform’: Space knots uniformly over range of x

  • weights (ndarray, shape (n,), optional) – Observation weights for weighted least squares.

  • use_sparse (bool, default=False) –

    Whether to use sparse matrix operations for B-spline basis.

    When to use sparse: - Large problems (n > 500, n_basis > 20) - B-spline basis (has compact support) - Memory-constrained environments

    Benefits: - ~10-100× speedup for large problems - Reduced memory usage: O(n × degree) vs O(n × n_basis) - Automatic method selection (direct/CG/MINRES)

    Note: Only available for ‘bspline’ basis type. Cubic splines have global support and do not benefit from sparse operations.

  • lambda_ (float | None)

Returns:

result – Fitted GAM result containing: - coefficients: Spline coefficients - fitted_values: Predicted values at x - lambda_: Smoothing parameter used - edf: Effective degrees of freedom - basis: Basis object for prediction - residuals: y - fitted_values

Return type:

GAMResult

Notes

The model minimizes the penalized least squares criterion:

||y - Xβ||² + λ β’Sβ

where X is the basis matrix and S is the penalty matrix.

For automatic smoothing parameter selection (lambda_=None), uses GCV:

GCV(λ) = (n * RSS) / (n - tr(H))²

Examples

>>> import numpy as np
>>> from aurora.models.gam import fit_gam
>>> # Generate noisy data
>>> x = np.linspace(0, 1, 100)
>>> y = np.sin(2 * np.pi * x) + 0.1 * np.random.randn(100)
>>> # Fit GAM with automatic smoothing
>>> result = fit_gam(x, y, n_basis=12)
>>> print(f"EDF: {result.edf:.2f}")
>>> print(f"Lambda: {result.lambda_:.4f}")
>>> # Make predictions
>>> x_new = np.linspace(0, 1, 200)
>>> y_pred = result.predict(x_new)

References

Wood, S.N. (2017). Generalized Additive Models: An Introduction with R.

Chapman and Hall/CRC.

Eilers, P.H.C. & Marx, B.D. (1996). Flexible smoothing with B-splines and

penalties. Statistical Science, 11(2), 89-121.

class aurora.models.gam.GAMResult(coefficients, fitted_values, residuals, lambda_, edf, basis, x, y, weights=None, gcv_score=None)[source]

Bases: object

Result of fitting a Generalized Additive Model.

Parameters:

  • coefficients (ndarray) – Spline coefficients.

  • fitted_values (ndarray) – Fitted values at training data points.

  • residuals (ndarray) – Residuals (y - fitted_values).

  • lambda (float) – Smoothing parameter used.

  • edf (float) – Effective degrees of freedom.

  • basis (object) – Basis object (BSplineBasis or CubicSplineBasis).

  • x (ndarray) – Training predictor values.

  • y (ndarray) – Training response values.

  • weights (ndarray, optional) – Observation weights.

  • gcv_score (float, optional) – GCV score if lambda was selected automatically.

  • lambda_ (float)

Variables:

  • attributes. (All parameters are stored as)

  • n_obs (int) – Number of observations.

  • lambda_opt (float) – Alias for lambda_ (optimal smoothing parameter).

  • r_squared (float) – Coefficient of determination (R-squared), computed from the residuals as 1 - rss / tss; can be negative.

  • points (>>> # Predict at new)

  • 2)) (>>> y_pred = result.predict(np.linspace(0, 2 * np.pi,)

  • print(result.summary()) (>>>)

  • variables (>>> # Using dict with named)

  • { (>>> data =)

  • 'response' (...)

  • 'temp' (...)

  • 'humidity' (...)

  • } (...)

  • data) (>>> result = fit_gam_formula("response ~ s(temp) + humidity",)

  • print(result.summary())

See also

AdditiveGAMResult

Additive GAM with multiple smooth terms.

fit_gam_formula

R-style formula interface.

fit_glm

GLM fitting function.

References

Wood, S.N. (2017). Generalized Additive Models: An Introduction with R. CRC Press.

property r_squared: float

Coefficient of determination (R²).

Returns:

r_squared – R² value, proportion of variance explained by the model.

Return type:

float

property lambda_opt: float

Alias for lambda_ (optimal smoothing parameter).

Returns:

lambda_opt – The smoothing parameter used in the fit.

Return type:

float

predict(x_new)[source]

Predict at new x values.

Parameters:

x_new (ndarray, shape (m,)) – New predictor values.

Returns:

y_pred – Predicted values.

Return type:

ndarray, shape (m,)

summary()[source]

Generate summary string of fit.

Returns:

summary – Formatted summary of model fit.

Return type:

str

__repr__()[source]

Return string representation.

Return type:

str

aurora.models.gam.fit_additive_gam(X, y, smooth_terms, parametric_terms=None, weights=None, method='GCV')[source]

Fit additive GAM with multiple smooth and parametric terms.

This function fits a model of the form:

y = β₀ + f₁(x₁) + f₂(x₂) + … + βₖxₖ + ε

where f_j are smooth functions represented as penalized splines, and the last terms are linear (parametric).

Parameters:

  • X (ndarray, shape (n, p)) – Predictor matrix.

  • y (ndarray, shape (n,)) – Response variable.

  • smooth_terms (list of SmoothTerm) – Specifications for smooth terms. Each defines which column of X to smooth and how.

  • parametric_terms (list of ParametricTerm, optional) – Specifications for parametric (linear) terms.

  • weights (ndarray, shape (n,), optional) – Observation weights for weighted least squares.

  • method ({'GCV', 'REML'}, default='GCV') – Method for smoothing parameter selection: - ‘GCV’: Generalized Cross-Validation - ‘REML’: Restricted Maximum Likelihood Note: Currently both methods use a single λ for all smooth terms.

Returns:

result – Fitted additive GAM result.

Return type:

AdditiveGAMResult

Notes

The model minimizes the penalized least squares criterion:

||y - Xβ||² + Σⱼ λⱼ βⱼ’Sⱼβⱼ

Each smooth term has its own smoothing parameter λⱼ selected via GCV.

Examples

>>> import numpy as np
>>> from aurora.models.gam import fit_additive_gam, SmoothTerm
>>> # Generate data with two nonlinear effects
>>> n = 200
>>> X = np.random.randn(n, 2)
>>> y = np.sin(2 * X[:, 0]) + np.cos(X[:, 1]) + 0.1 * np.random.randn(n)
>>> # Fit additive GAM
>>> result = fit_additive_gam(
...     X, y,
...     smooth_terms=[
...         SmoothTerm(variable=0, n_basis=10),
...         SmoothTerm(variable=1, n_basis=10)
...     ]
... )
>>> print(result.summary())

References

Wood, S.N. (2017). Generalized Additive Models: An Introduction with R.

aurora.models.gam.fit_gam_formula(formula, data, weights=None, method='GCV')[source]

Fit additive GAM using R-style formula syntax.

Convenience function that parses a formula string and fits a GAM.

Parameters:

  • formula (str) – Formula string in R-style syntax, e.g.: - “y ~ s(x1) + s(x2)” - “y ~ s(x1, n_basis=15) + s(x2, basis=’cubic’) + x3”

  • data (dict or ndarray) – If dict: mapping from variable names to arrays If ndarray: shape (n, p) array where formula uses column indices

  • weights (ndarray, shape (n,), optional) – Observation weights.

  • method ({'GCV', 'REML'}, default='GCV') – Method for smoothing parameter selection.

Returns:

result – Fitted additive GAM result.

Return type:

AdditiveGAMResult

Examples

>>> import numpy as np
>>> from aurora.models.gam import fit_gam_formula
>>> # Using column indices with array
>>> n = 200
>>> X = np.random.randn(n, 3)
>>> y = np.sin(2 * X[:, 0]) + np.cos(X[:, 1]) + 0.5 * X[:, 2] + 0.1 * np.random.randn(n)
>>> result = fit_gam_formula("0 ~ s(1) + s(2) + 3", np.column_stack([y, X]))
>>> print(result.summary())

>>> # Using dict with named variables
>>> data = {
...     'response': y,
...     'temp': X[:, 0],
...     'pressure': X[:, 1],
...     'humidity': X[:, 2]
... }
>>> result = fit_gam_formula("response ~ s(temp) + s(pressure) + humidity", data)

Notes

When using column indices (integers), the data should be a 2D array where the first column can be the response variable.

When using variable names (strings), data should be a dict mapping names to 1D arrays.

class aurora.models.gam.AdditiveGAMResult(parametric_coef, smooth_coef, smooth_bases, lambda_values, edf_values, fitted_values, residuals, X_parametric, X_train, y, smooth_terms, parametric_terms, weights=None, gcv_score=None)[source]

Bases: object

Result of fitting an additive GAM with multiple terms.

Parameters:

  • parametric_coef (ndarray) – Coefficients for parametric terms (including intercept).

  • smooth_coef (dict) – Dictionary mapping smooth term names to their coefficients.

  • smooth_bases (dict) – Dictionary mapping smooth term names to their basis objects.

  • lambda_values (dict) – Dictionary mapping smooth term names to their smoothing parameters.

  • edf_values (dict) – Dictionary mapping smooth term names to their effective degrees of freedom.

  • fitted_values (ndarray) – Fitted values at training data.

  • residuals (ndarray) – Residuals (y - fitted_values).

  • X_parametric (ndarray) – Parametric design matrix.

  • X_train (ndarray) – Full design matrix used for training.

  • y (ndarray) – Training response values.

  • smooth_terms (list of SmoothTerm) – Smooth term specifications.

  • parametric_terms (list of ParametricTerm) – Parametric term specifications.

  • weights (ndarray, optional) – Observation weights.

  • gcv_score (float, optional) – GCV score if lambdas were selected automatically.

property r_squared: float

Coefficient of determination (R²).

Returns:

r_squared – R² value, proportion of variance explained by the model.

Return type:

float

predict(X_new)[source]

Predict at new data points.

Parameters:

X_new (ndarray, shape (m, n_features)) – New predictor values. Must have same number of columns as training data.

Returns:

y_pred – Predicted values.

Return type:

ndarray, shape (m,)

Notes

Predictions are computed as:

ŷ = X_param @ β_param + Σ X_smooth_j @ β_smooth_j

summary()[source]

Generate summary string of additive GAM fit.

Returns:

summary – Formatted summary with parametric and smooth terms.

Return type:

str

__repr__()[source]

Return string representation.

Return type:

str

class aurora.models.gam.SmoothTerm(variable, basis_type='bspline', n_basis=10, penalty_order=2, by=None, lambda_=None, knot_method='quantile')[source]

Bases: object

Specification of a smooth term s(x, …)

This class defines how a predictor variable should be smoothed in a GAM model.

Parameters:

  • variable (str or int) – Variable name (if using DataFrame) or column index (if using array).

  • basis_type ({'bspline', 'cubic', 'tp', 'cr', 'ps'}, default='bspline') – Type of spline basis: - ‘bspline’: B-spline basis (default) - ‘cubic’: Natural cubic splines - ‘tp’: Thin plate splines (future) - ‘cr’: Cubic regression splines (future) - ‘ps’: P-splines (future)

  • n_basis (int, default=10) – Number of basis functions (k in mgcv terminology).

  • penalty_order (int, default=2) – Order of difference penalty (usually 2 for second derivative).

  • by (str or int, optional) – Factor variable for by-factor smooths (not yet implemented).

  • lambda (float, optional) – Fixed smoothing parameter. If None, selected automatically.

  • knot_method ({'quantile', 'uniform'}, default='quantile') – Method for placing knots.

  • lambda_ (float | None)

Examples

>>> # Smooth term with default settings
>>> s1 = SmoothTerm(variable='x1')

>>> # Smooth term with custom settings
>>> s2 = SmoothTerm(
...     variable='x2',
...     basis_type='cubic',
...     n_basis=15,
...     lambda_=0.1
... )

>>> # Using column index instead of name
>>> s3 = SmoothTerm(variable=0, n_basis=12)

Notes

This is inspired by mgcv’s s() function in R but simplified for initial implementation.

variable: str | int
basis_type: Literal['bspline', 'cubic', 'tp', 'cr', 'ps'] = 'bspline'
n_basis: int = 10
penalty_order: int = 2
by: str | int | None = None
lambda_: float | None = None
knot_method: Literal['quantile', 'uniform'] = 'quantile'
__post_init__()[source]

Validate parameters after initialization.

class aurora.models.gam.ParametricTerm(variable)[source]

Bases: object

Specification of a parametric (linear) term.

Parameters:

variable (str or int) – Variable name or column index.

Examples

>>> p1 = ParametricTerm(variable='age')
>>> p2 = ParametricTerm(variable=2)  # column index
variable: str | int
class aurora.models.gam.TensorTerm(variables, basis_types=None, n_basis=None, lambdas=None)[source]

Bases: object

Specification of a tensor product smooth te(x1, x2, …).

Tensor product smooths model interactions between variables using the tensor product of marginal basis functions.

Parameters:

  • variables (tuple of (str or int)) – Tuple of variable names or column indices (length 2 or more).

  • basis_types (tuple of str, optional) – Basis type for each variable. If None, uses ‘bspline’ for all.

  • n_basis (tuple of int, optional) – Number of basis functions for each variable. If None, uses 10 for all.

  • lambdas (tuple of float, optional) – Fixed smoothing parameters for each direction. If None, selected automatically.

Examples

>>> # 2D tensor product with defaults
>>> te1 = TensorTerm(variables=(0, 1))

>>> # Custom basis sizes
>>> te2 = TensorTerm(variables=('x1', 'x2'), n_basis=(12, 12))

>>> # Different basis types
>>> te3 = TensorTerm(
...     variables=(0, 1),
...     basis_types=('bspline', 'cubic'),
...     n_basis=(10, 8)
... )

Notes

Tensor products are useful for modeling interactions. They are more flexible than additive models but require more data and computation.

The tensor product te(x1, x2) creates a surface f(x1, x2) rather than the sum f1(x1) + f2(x2).

variables: tuple[str | int, ...]
basis_types: tuple[str, ...] | None = None
n_basis: tuple[int, ...] | None = None
lambdas: tuple[float, ...] | None = None
__post_init__()[source]

Validate parameters after initialization.

aurora.models.gam.plot_smooth(result, term=None, confidence_level=0.95, n_points=100, partial_residuals=True, ax=None, figsize=(8, 6), title=None, xlabel=None, ylabel=None)[source]

Plot a smooth term with confidence bands.

Parameters:

  • result (GAMResult or AdditiveGAMResult) – Fitted GAM result object.

  • term (int, str, or None) – For AdditiveGAMResult: term name like “s(0)” or variable index. For GAMResult: should be None (univariate GAM).

  • confidence_level (float, default=0.95) – Confidence level for bands (e.g., 0.95 for 95% CI).

  • n_points (int, default=100) – Number of evaluation points for smooth curve.

  • partial_residuals (bool, default=True) – Whether to show partial residuals.

  • ax (matplotlib Axes, optional) – Axes to plot on. If None, creates new figure.

  • figsize (tuple, default=(8, 6)) – Figure size if creating new figure.

  • title (str, optional) – Plot title. Auto-generated if None.

  • xlabel (str, optional) – X-axis label. Auto-generated if None.

  • ylabel (str, optional) – Y-axis label. Auto-generated if None.

Returns:

fig – The figure containing the plot.

Return type:

matplotlib Figure

Raises:

Examples

>>> import numpy as np
>>> from aurora.models.gam import fit_gam, plot_smooth
>>> x = np.linspace(0, 10, 100)
>>> y = np.sin(x) + 0.1 * np.random.randn(100)
>>> result = fit_gam(x, y, n_basis=15)
>>> fig = plot_smooth(result)

>>> # For additive GAM
>>> from aurora.models.gam import fit_additive_gam, SmoothTerm
>>> X = np.random.randn(200, 2)
>>> y = np.sin(X[:, 0]) + np.cos(X[:, 1]) + 0.1 * np.random.randn(200)
>>> result = fit_additive_gam(
...     X, y,
...     smooth_terms=[SmoothTerm(variable=0), SmoothTerm(variable=1)]
... )
>>> fig = plot_smooth(result, term="s(0)")

Notes

Confidence bands use the Bayesian posterior covariance of the penalized smooth, Vp (Wood 2017, §6.10):

Var(f(x)) = σ̂² · B(x) (X’X + λS)⁻¹ B(x)’

where B(x) is the basis matrix and σ̂² = RSS / (n - edf) is the scale estimate corrected for the effective degrees of freedom. This is the Bayesian covariance (the frequentist Ve would insert an extra X’WX factor between the inverses); Bayesian bands for penalized splines have good across-the-function frequentist coverage (Marra & Wood 2012).

Partial residuals for term j are:

r_j = y - f_{-j}(x)

where f_{-j} excludes term j.

aurora.models.gam.plot_all_smooths(result, ncols=2, confidence_level=0.95, figsize_per_plot=(6, 4), partial_residuals=True)[source]

Plot all smooth terms in a grid layout.

Parameters:

  • result (AdditiveGAMResult) – Fitted additive GAM result.

  • ncols (int, default=2) – Number of columns in grid.

  • confidence_level (float, default=0.95) – Confidence level for bands.

  • figsize_per_plot (tuple, default=(6, 4)) – Size of each subplot.

  • partial_residuals (bool, default=True) – Whether to show partial residuals.

Returns:

fig – Figure with all smooth terms plotted.

Return type:

matplotlib Figure

Examples

>>> from aurora.models.gam import fit_additive_gam, SmoothTerm
>>> import numpy as np
>>> X = np.random.randn(200, 3)
>>> y = np.sin(X[:, 0]) + np.cos(X[:, 1]) + X[:, 2]**2 + 0.1 * np.random.randn(200)
>>> result = fit_additive_gam(
...     X, y,
...     smooth_terms=[
...         SmoothTerm(variable=0),
...         SmoothTerm(variable=1),
...         SmoothTerm(variable=2)
...     ]
... )
>>> fig = plot_all_smooths(result, ncols=3)
aurora.models.gam.parse_formula(formula)[source]

Parse R-style GAM/GAMM formula into term specifications.

Parameters:

formula (str) – Formula string in R-style syntax, e.g.: - “y ~ s(x1) + s(x2)” - “y ~ s(x1, n_basis=10) + s(x2, basis=’cubic’) + x3” - “y ~ s(x1) + x2 + (1 | subject)” # Random intercept - “y ~ s(x1) + (1 + time | subject)” # Random intercept + slope - “y ~ s(x1) + (1 | clinic/subject)” # Nested random effects - “y ~ s(x1) + (1 | subject) + (1 | clinic)” # Crossed random effects

Returns:

spec – Parsed formula specification with response, smooth terms, parametric terms, and random effects.

Return type:

FormulaSpec

Examples

>>> from aurora.models.gam.formula import parse_formula
>>> spec = parse_formula("y ~ s(x1) + s(x2) + x3")
>>> spec.response
'y'
>>> len(spec.smooth_terms)
2
>>> len(spec.parametric_terms)
1

>>> # With random effects
>>> spec = parse_formula("y ~ s(x1) + x2 + (1 | subject)")
>>> len(spec.random_effects)
1
>>> spec.random_effects[0].grouping
'subject'

Notes

Supported smooth term syntax: - s(variable): Default B-spline with 10 basis functions - s(variable, n_basis=15): Custom number of basis functions - s(variable, basis=’cubic’): Cubic spline basis - s(variable, basis=’bspline’, n_basis=12): Combined options

Supported random effects syntax (lme4-style): - (1 | group): Random intercept - (x | group): Random slope (no intercept) - (1 + x | group): Random intercept + slope - (x + y | group): Multiple random slopes - (1 | a/b): Nested random effects (a within b) - (1 | a) + (1 | b): Crossed random effects

Variable names can be column names (when using DataFrames) or column indices (when using arrays).

The intercept is always included automatically for fixed effects.

class aurora.models.gam.FormulaSpec(response, smooth_terms, parametric_terms, random_effects=<factory>)[source]

Bases: object

Parsed formula specification.

Variables:

  • response (str) – Name of the response variable.

  • smooth_terms (list of SmoothTerm) – Smooth term specifications.

  • parametric_terms (list of ParametricTerm) – Parametric term specifications.

  • random_effects (list of RandomEffect) – Random effects specifications (for GAMM models).

Parameters:
response: str
smooth_terms: list[SmoothTerm]
parametric_terms: list[ParametricTerm]
random_effects: list

Fitting

aurora.models.gam.fitting.fit_gam(x, y, n_basis=10, basis_type='bspline', degree=3, penalty_order=2, lambda_=None, lambda_min=1e-6, lambda_max=1e6, knot_method='quantile', weights=None, use_sparse=False)[source]

Fit univariate Generalized Additive Model using penalized splines.

This function fits a smooth function f(x) to data (x, y) using:

y = f(x) + ε

where f is represented as a linear combination of basis functions with a roughness penalty.

Parameters:

  • x (ndarray, shape (n,)) – Predictor variable.

  • y (ndarray, shape (n,)) – Response variable.

  • n_basis (int, default=10) – Number of basis functions to use.

  • basis_type ({'bspline', 'cubic'}, default='bspline') – Type of spline basis: - ‘bspline’: B-spline basis (local support, partition of unity) - ‘cubic’: Natural cubic spline basis (global support)

  • degree (int, default=3) – Degree of splines (3 for cubic splines).

  • penalty_order (int, default=2) – Order of difference penalty (2 approximates second derivative).

  • lambda (float, optional) – Smoothing parameter. If None, selected automatically via GCV.

  • lambda_min (float, default=1e-6) – Minimum lambda for GCV search.

  • lambda_max (float, default=1e6) – Maximum lambda for GCV search.

  • knot_method ({'quantile', 'uniform'}, default='quantile') – Method for placing knots: - ‘quantile’: Place knots at quantiles of x - ‘uniform’: Space knots uniformly over range of x

  • weights (ndarray, shape (n,), optional) – Observation weights for weighted least squares.

  • use_sparse (bool, default=False) –

    Whether to use sparse matrix operations for B-spline basis.

    When to use sparse: - Large problems (n > 500, n_basis > 20) - B-spline basis (has compact support) - Memory-constrained environments

    Benefits: - ~10-100× speedup for large problems - Reduced memory usage: O(n × degree) vs O(n × n_basis) - Automatic method selection (direct/CG/MINRES)

    Note: Only available for ‘bspline’ basis type. Cubic splines have global support and do not benefit from sparse operations.

  • lambda_ (float | None)

Returns:

result – Fitted GAM result containing: - coefficients: Spline coefficients - fitted_values: Predicted values at x - lambda_: Smoothing parameter used - edf: Effective degrees of freedom - basis: Basis object for prediction - residuals: y - fitted_values

Return type:

GAMResult

Notes

The model minimizes the penalized least squares criterion:

||y - Xβ||² + λ β’Sβ

where X is the basis matrix and S is the penalty matrix.

For automatic smoothing parameter selection (lambda_=None), uses GCV:

GCV(λ) = (n * RSS) / (n - tr(H))²

Examples

>>> import numpy as np
>>> from aurora.models.gam import fit_gam
>>> # Generate noisy data
>>> x = np.linspace(0, 1, 100)
>>> y = np.sin(2 * np.pi * x) + 0.1 * np.random.randn(100)
>>> # Fit GAM with automatic smoothing
>>> result = fit_gam(x, y, n_basis=12)
>>> print(f"EDF: {result.edf:.2f}")
>>> print(f"Lambda: {result.lambda_:.4f}")
>>> # Make predictions
>>> x_new = np.linspace(0, 1, 200)
>>> y_pred = result.predict(x_new)

References

Wood, S.N. (2017). Generalized Additive Models: An Introduction with R.

Chapman and Hall/CRC.

Eilers, P.H.C. & Marx, B.D. (1996). Flexible smoothing with B-splines and

penalties. Statistical Science, 11(2), 89-121.

aurora.models.gam.additive.fit_additive_gam(X, y, smooth_terms, parametric_terms=None, weights=None, method='GCV')[source]

Fit additive GAM with multiple smooth and parametric terms.

This function fits a model of the form:

y = β₀ + f₁(x₁) + f₂(x₂) + … + βₖxₖ + ε

where f_j are smooth functions represented as penalized splines, and the last terms are linear (parametric).

Parameters:

  • X (ndarray, shape (n, p)) – Predictor matrix.

  • y (ndarray, shape (n,)) – Response variable.

  • smooth_terms (list of SmoothTerm) – Specifications for smooth terms. Each defines which column of X to smooth and how.

  • parametric_terms (list of ParametricTerm, optional) – Specifications for parametric (linear) terms.

  • weights (ndarray, shape (n,), optional) – Observation weights for weighted least squares.

  • method ({'GCV', 'REML'}, default='GCV') – Method for smoothing parameter selection: - ‘GCV’: Generalized Cross-Validation - ‘REML’: Restricted Maximum Likelihood Note: Currently both methods use a single λ for all smooth terms.

Returns:

result – Fitted additive GAM result.

Return type:

AdditiveGAMResult

Notes

The model minimizes the penalized least squares criterion:

||y - Xβ||² + Σⱼ λⱼ βⱼ’Sⱼβⱼ

Each smooth term has its own smoothing parameter λⱼ selected via GCV.

Examples

>>> import numpy as np
>>> from aurora.models.gam import fit_additive_gam, SmoothTerm
>>> # Generate data with two nonlinear effects
>>> n = 200
>>> X = np.random.randn(n, 2)
>>> y = np.sin(2 * X[:, 0]) + np.cos(X[:, 1]) + 0.1 * np.random.randn(n)
>>> # Fit additive GAM
>>> result = fit_additive_gam(
...     X, y,
...     smooth_terms=[
...         SmoothTerm(variable=0, n_basis=10),
...         SmoothTerm(variable=1, n_basis=10)
...     ]
... )
>>> print(result.summary())

References

Wood, S.N. (2017). Generalized Additive Models: An Introduction with R.

aurora.models.gam.additive.fit_gam_formula(formula, data, weights=None, method='GCV')[source]

Fit additive GAM using R-style formula syntax.

Convenience function that parses a formula string and fits a GAM.

Parameters:

  • formula (str) – Formula string in R-style syntax, e.g.: - “y ~ s(x1) + s(x2)” - “y ~ s(x1, n_basis=15) + s(x2, basis=’cubic’) + x3”

  • data (dict or ndarray) – If dict: mapping from variable names to arrays If ndarray: shape (n, p) array where formula uses column indices

  • weights (ndarray, shape (n,), optional) – Observation weights.

  • method ({'GCV', 'REML'}, default='GCV') – Method for smoothing parameter selection.

Returns:

result – Fitted additive GAM result.

Return type:

AdditiveGAMResult

Examples

>>> import numpy as np
>>> from aurora.models.gam import fit_gam_formula
>>> # Using column indices with array
>>> n = 200
>>> X = np.random.randn(n, 3)
>>> y = np.sin(2 * X[:, 0]) + np.cos(X[:, 1]) + 0.5 * X[:, 2] + 0.1 * np.random.randn(n)
>>> result = fit_gam_formula("0 ~ s(1) + s(2) + 3", np.column_stack([y, X]))
>>> print(result.summary())

>>> # Using dict with named variables
>>> data = {
...     'response': y,
...     'temp': X[:, 0],
...     'pressure': X[:, 1],
...     'humidity': X[:, 2]
... }
>>> result = fit_gam_formula("response ~ s(temp) + s(pressure) + humidity", data)

Notes

When using column indices (integers), the data should be a 2D array where the first column can be the response variable.

When using variable names (strings), data should be a dict mapping names to 1D arrays.

Result

class aurora.models.gam.result.GAMResult(coefficients, fitted_values, residuals, lambda_, edf, basis, x, y, weights=None, gcv_score=None)[source]

Bases: object

Result of fitting a Generalized Additive Model.

Parameters:

  • coefficients (ndarray) – Spline coefficients.

  • fitted_values (ndarray) – Fitted values at training data points.

  • residuals (ndarray) – Residuals (y - fitted_values).

  • lambda (float) – Smoothing parameter used.

  • edf (float) – Effective degrees of freedom.

  • basis (object) – Basis object (BSplineBasis or CubicSplineBasis).

  • x (ndarray) – Training predictor values.

  • y (ndarray) – Training response values.

  • weights (ndarray, optional) – Observation weights.

  • gcv_score (float, optional) – GCV score if lambda was selected automatically.

  • lambda_ (float)

Variables:

  • attributes. (All parameters are stored as)

  • n_obs (int) – Number of observations.

  • lambda_opt (float) – Alias for lambda_ (optimal smoothing parameter).

  • r_squared (float) – Coefficient of determination (R-squared), computed from the residuals as 1 - rss / tss; can be negative.

  • points (>>> # Predict at new)

  • 2)) (>>> y_pred = result.predict(np.linspace(0, 2 * np.pi,)

  • print(result.summary()) (>>>)

  • variables (>>> # Using dict with named)

  • { (>>> data =)

  • 'response' (...)

  • 'temp' (...)

  • 'humidity' (...)

  • } (...)

  • data) (>>> result = fit_gam_formula("response ~ s(temp) + humidity",)

  • print(result.summary())

See also

AdditiveGAMResult

Additive GAM with multiple smooth terms.

fit_gam_formula

R-style formula interface.

fit_glm

GLM fitting function.

References

Wood, S.N. (2017). Generalized Additive Models: An Introduction with R. CRC Press.

property r_squared: float

Coefficient of determination (R²).

Returns:

r_squared – R² value, proportion of variance explained by the model.

Return type:

float

property lambda_opt: float

Alias for lambda_ (optimal smoothing parameter).

Returns:

lambda_opt – The smoothing parameter used in the fit.

Return type:

float

predict(x_new)[source]

Predict at new x values.

Parameters:

x_new (ndarray, shape (m,)) – New predictor values.

Returns:

y_pred – Predicted values.

Return type:

ndarray, shape (m,)

summary()[source]

Generate summary string of fit.

Returns:

summary – Formatted summary of model fit.

Return type:

str

__repr__()[source]

Return string representation.

Return type:

str

class aurora.models.gam.additive.AdditiveGAMResult(parametric_coef, smooth_coef, smooth_bases, lambda_values, edf_values, fitted_values, residuals, X_parametric, X_train, y, smooth_terms, parametric_terms, weights=None, gcv_score=None)[source]

Bases: object

Result of fitting an additive GAM with multiple terms.

Parameters:

  • parametric_coef (ndarray) – Coefficients for parametric terms (including intercept).

  • smooth_coef (dict) – Dictionary mapping smooth term names to their coefficients.

  • smooth_bases (dict) – Dictionary mapping smooth term names to their basis objects.

  • lambda_values (dict) – Dictionary mapping smooth term names to their smoothing parameters.

  • edf_values (dict) – Dictionary mapping smooth term names to their effective degrees of freedom.

  • fitted_values (ndarray) – Fitted values at training data.

  • residuals (ndarray) – Residuals (y - fitted_values).

  • X_parametric (ndarray) – Parametric design matrix.

  • X_train (ndarray) – Full design matrix used for training.

  • y (ndarray) – Training response values.

  • smooth_terms (list of SmoothTerm) – Smooth term specifications.

  • parametric_terms (list of ParametricTerm) – Parametric term specifications.

  • weights (ndarray, optional) – Observation weights.

  • gcv_score (float, optional) – GCV score if lambdas were selected automatically.

property r_squared: float

Coefficient of determination (R²).

Returns:

r_squared – R² value, proportion of variance explained by the model.

Return type:

float

predict(X_new)[source]

Predict at new data points.

Parameters:

X_new (ndarray, shape (m, n_features)) – New predictor values. Must have same number of columns as training data.

Returns:

y_pred – Predicted values.

Return type:

ndarray, shape (m,)

Notes

Predictions are computed as:

ŷ = X_param @ β_param + Σ X_smooth_j @ β_smooth_j

summary()[source]

Generate summary string of additive GAM fit.

Returns:

summary – Formatted summary with parametric and smooth terms.

Return type:

str

__repr__()[source]

Return string representation.

Return type:

str