FunctionalGAM(
response,
functional_terms,
*,
scalar_terms=None,
family=None,
)
Fits a model where the response is scalar but one or more predictors are functional, i.e. each observation carries an entire curve X_i(t) measured over a domain (such as a temperature profile over time, or a spectral curve over wavelength), rather than a single number. Each functional covariate contributes a linear functional term to the predictor,
\int X_i(t)\,\beta(t)\,dt,
where beta(t) is an unknown smooth coefficient function that must itself be estimated. This integral is approximated numerically (trapezoidal quadrature over the observed grid) and beta(t) is expanded in a B-spline or Fourier basis with a roughness penalty, turning the infinite-dimensional problem of estimating a function into a finite penalized regression that can be fit with the same machinery as any other GAM smooth term.
Use FunctionalGAM when your predictors are naturally curves or profiles rather than scalars, and you want to recover how different regions of the domain contribute to the response (e.g. “does temperature early in the season matter more than temperature late in the season?”).
Parameters
response: str-
Name of the scalar response variable.
functional_terms: list[FunctionalTerm | dict]-
List of FunctionalTerm specifications (or dicts with the same keys), one per functional covariate.
scalar_terms: str | None = None-
Optional formula string for additional scalar smooth/linear terms (e.g. "s(temperature) + humidity") fit alongside the functional terms.
family: Family | None = None-
Response distribution family. Defaults to Gaussian().
Notes
For each functional term, the coefficient function is expanded as \beta(t) = \sum_{k=1}^{K} c_k \phi_k(t) in a basis \{\phi_k\} (B-spline or Fourier), so the functional effect for observation i becomes a finite inner product with a numerically integrated design column:
\int X_i(t)\,\beta(t)\,dt \;\approx\;
\sum_{k=1}^{K} c_k \underbrace{\sum_t X_i(t)\,\phi_k(t)\,w_t}_{J_{i,k}}
where w_t are trapezoidal quadrature weights. The coefficients c_k are penalized by a difference penalty (B-spline) or a frequency-based penalty (Fourier) of order penalty_order, controlling the smoothness of the recovered beta(t). All functional and scalar design columns are combined into one design matrix and fit jointly via penalized IRLS (pirls_fit), so the smoothing parameters for each functional term’s coefficient function, and for any scalar smooth terms, are selected simultaneously.
Examples
import numpy as np
from whittaker.functional import FunctionalGAM, FunctionalTerm
rng = np.random.default_rng(0)
n, T = 300, 50
t_grid = np.linspace(0, 1, T)
beta_true = np.sin(2 * np.pi * t_grid)
X_curves = rng.normal(size=(n, T)) + np.sin(3 * t_grid)
y = X_curves @ beta_true / T + rng.normal(scale=0.3, size=n)
model = FunctionalGAM("y", [FunctionalTerm(name="X_curves", n_basis=12)])
model.fit({"y": y, "X_curves": X_curves})
cf = model.coefficient_function("X_curves")
print(cf.values[:5])
[0.29887787 0.33565746 0.3707274 0.40413803 0.4359397 ]
Attributes
|
Name
|
Description
|
|
coefficients
|
Fitted coefficient vector for the combined design matrix.
|
|
deviance
|
Deviance of the fitted model.
|
|
edf_total
|
Total effective degrees of freedom across all functional and scalar terms.
|
|
functional_terms
|
List of FunctionalTerm specifications used by this model.
|
|
is_fitted
|
Whether fit() has been called successfully.
|
|
response
|
Name of the scalar response variable.
|
|
scale
|
Estimated scale (dispersion) parameter of the fitted model.
|
coefficients
Fitted coefficient vector for the combined design matrix.
deviance
Deviance of the fitted model.
edf_total
Total effective degrees of freedom across all functional and scalar terms.
functional_terms
functional_terms: list[FunctionalTerm]
is_fitted
Whether fit() has been called successfully.
response
Name of the scalar response variable.
scale
Estimated scale (dispersion) parameter of the fitted model.
Methods
|
Name
|
Description
|
|
coefficient_function()
|
Extract the estimated coefficient function beta(t) for a functional term.
|
|
edf()
|
Effective degrees of freedom per functional term.
|
|
fit()
|
Fit the functional GAM.
|
|
predict()
|
Predict on new data.
|
|
summary()
|
Build a text summary of the fitted functional GAM.
|
coefficient_function()
Extract the estimated coefficient function beta(t) for a functional term.
coefficient_function(
term_name,
*,
n_grid=200,
level=0.95,
)
Parameters
term_name: str-
Name of the functional term.
n_grid: int = 200-
Number of grid points for evaluation.
level: float = 0.95-
Confidence level for pointwise intervals.
edf()
Effective degrees of freedom per functional term.
fit()
fit(
data,
*,
method="REML",
select=False,
)
For each functional term, builds its basis matrix and penalty over the observed grid, computes the numerically integrated functional design columns (mean-centered for identifiability), and combines them with any scalar terms into a single design matrix. The combined model is then fit by penalized IRLS (pirls_fit), jointly selecting smoothing parameters for every functional term’s coefficient function and any scalar smooths.
Parameters
data: InputData-
Column-oriented data. Scalar covariates and the response are 1-D arrays. Functional covariates are 2-D arrays of shape (n, T) where T is the number of grid points.
method: str = "REML"-
Smoothing parameter selection method (e.g. "REML", "GCV", "ML").
select: bool = False-
Enable double-penalty variable selection for the scalar terms.
Returns
FunctionalGAM-
Returns
self for method chaining.
predict()
predict(
new_data,
*,
se=False,
)
Rebuilds the functional design columns for new_data using the basis matrices fit on the training data (so no new basis/penalty is estimated), forms the linear predictor, and maps it through the family’s inverse link to the response scale.
Parameters
new_data: InputData-
Data dict with the same functional and scalar covariates as training data.
se: bool = False-
If
True, return (predictions, standard_errors) instead of just predictions, where standard errors are computed on the linear predictor scale from the reconstructed training-data information matrix (X'WX + S).
Returns
NDArray or tuple[NDArray, NDArray]-
summary()
Build a text summary of the fitted functional GAM.
Reports the response name, family, number of observations, total EDF, deviance, and scale, followed by per-functional-term details (basis type, number of basis functions, domain, and EDF) and, if present, the scalar terms formula.
Returns
str-
Multi-line summary text.