StrctTerm

class liesel_gam.StrctTerm(basis, penalty, scale, name='', inference=None, coef_name=None, _update_on_init=True, validate_scalar_scale=True)

Bases: UserVar

General structured additive term.

You probably want to initialize a term using StrctTerm.f(), which will automatically take the penalty matrix from the supplied basis and has automatic naming that is convenient in most situations.

A structured additive term represents a smooth or structured effect in a generalized additive model. The term wraps a design/basis matrix together with a prior/penalty and a set of coefficients. The object exposes the coefficient variable and evaluates the term as the matrix-vector product of the basis and the coefficients. The term evaluates to basis @ coef.

Parameters:

• basis (Basis) – A Basis instance that produces the design matrix for the term. The basis must evaluate to a 2-D array with shape (n_obs, n_bases).

• penalty (Var | Value | Array | ndarray | bool | number | bool | int | float | complex | None) – Penalty matrix or a variable/value wrapping the penalty used to construct the multivariate normal prior for the coefficients.

• scale (ScaleIG | VarIGPrior | Var | Array | ndarray | bool | number | bool | int | float | complex | None) – Scale parameter passed to the coefficient prior.

• name (str, default: '') – Term name.

• inference (Any, default: None) – Inference specification for this term’s coefficient.

• coef_name (str | None, default: None) – Name for the coefficient variable. If None, a default name based on name will be used.

• _update_on_init (bool, default: True) – If True (default) the internal calculation/graph nodes are evaluated during initialization. Set to False to delay initial evaluation.

• validate_scalar_scale (bool, default: True) – If True (default), the term will error if the scale variable does not hold a scalar scale. This is appropriate for most cases. If False, the term will also allow an array-valued scale variable of shape (nbases,). This only really makes sense when also reparameterizing the term using factor_scale(). Only use this if you know exactly what you are doing and you are certain that this is what you want.

See also

TermBuilder

Initializes structured additive terms.

BasisBuilder

Initializes structured additive term basis matrices.

Basis

Basis matrix object.

StrctTerm.f

Alternative, more convenient constructor.

StrctTensorProdTerm

Anisotropic tensor product terms.

Notes

The terms created by this builder generally have the form

\[s(\mathbf{x}_i) = \sum_{j=1}^J B_j(\mathbf{x}_i) \beta_j = \mathbf{b}(\mathbf{x}_i)^\top \boldsymbol{\beta}\]

where

• \(i=1, \dots, N\) is the observation index,

• \(\mathbf{x}_i^\top = [x_{i,1}, \dots, x_{i,M}]\) are covariate observations, where \(M\) denotes the number of covariates,

• \(\mathbf{b}(\mathbf{x}_i)^\top = [B_1(\mathbf{x}_i), \dots, B_J(\mathbf{x}_i)]\) are a set of basis function evaluations, and

• \(\boldsymbol{\beta}^\top = [\beta_1, \dots, \beta_J]\) are the corresponding coefficients.

In many cases, \(\mathbf{x}_i\) will consist of only one covariate.

The basis matrix for such a term is

\[\begin{split}\mathbf{B} = \begin{bmatrix} \mathbf{b}(\mathbf{x}_1)^\top \\ \vdots \\ \mathbf{b}(\mathbf{x}_N)^\top \end{bmatrix}.\end{split}\]

The coefficient receives a potentially rank-deficient multivariate normal prior

\[p(\boldsymbol{\beta}) \propto \left(\frac{1}{\tau^2}\right)^{ \operatorname{rk}(\mathbf{K})/2} \exp \left( - \frac{1}{\tau^2} \boldsymbol{\beta}^\top \mathbf{K} \boldsymbol{\beta} \right)\]

with the potentially rank-deficient penalty matrix \(\mathbf{K}\) of rank \(\operatorname{rk}(\mathbf{K})\). The variance parameter \(\tau^2\) acts as an inverse smoothing parameter.

The choice of basis functions \(B_j\) and penalty matrix \(\mathbf{K}\) determines the nature of the term.

Examples

>>> x = jnp.linspace(0.0, 1.0, 4)
>>> basis = Basis(
...     jnp.column_stack([jnp.ones_like(x), x]),
...     xname="x",
...     penalty=jnp.eye(2),
... )
>>> term = StrctTerm.f(basis, scale=1.0)
>>> term.name, term.nbases, term.value.shape
('f(x)', 2, (4,))

Methods

constrain	Apply a linear constraint to the term's basis and corresponding penalty.
diagonalize_penalty	Diagonalize the penalty via an eigenvalue decomposition.
f	Construct a smooth term from a Basis.
factor_scale	Turn this term into a partially standardized form.
replace_scale	Replace the scale variable and update the coefficient prior.
scale_penalty	Scale the penalty matrix by its infinity norm.

Attributes

basis	The basis matrix object of this term.
coef	The coefficient variable of this term.
nbases	Number of basis functions, equal to the number of basis-matrix columns.
scale	The scale variable used by the coefficient prior.
scale_is_factored	Whether the term has been reparameterized using factor_scale().