StrctInteractionTerm

StrctInteractionTerm#

class liesel_gam.StrctInteractionTerm(*marginals, common_scale=None, name='', inference=None, coef_name=None, basis_name=None, include_main_effects=False, _update_on_init=True)[source]#

Bases: UserVar

Anisotropic structured additive interaction term.

Parameters:

  • *marginals (StrctTerm | IndexingTerm | RITerm | MRFTerm) – Marginal terms.

  • common_scale (ScaleIG | VarIGPrior | Var | Array | ndarray | bool | number | bool | int | float | complex | None, default: None) – A single, common scale to cover all marginal dimensions, resulting in an isotropic tensor product. This means setting \(\tau^2_1 = \dots = \tau^2_M = \tau^2\) for all marginal smooths in the notation used below.

  • name (str, default: '') – Name of the term

  • coef_name (str | None, default: None) – Name of the coefficient variable. If None, created automatically based on name.

  • basis_name (str | None, default: None) – Name of the basis variable. This variable is internally created to represent the tensor product of the marginal basis matrices. If None, the name will be created automatically based on the names of the observed input variables to the marginal terms.

  • include_main_effects (bool, default: False) – If True, the marginal terms will be added to this term’s value.

  • _update_on_init (bool, default: True) – Whether to update the term upon initialization.

See also

StrctTerm

Basic (isotropic) structured additive term.

StrctTensorProdTerm

Full anisotropic tensor product term.

TermBuilder

Initializes structured additive terms.

BasisBuilder

Initializes structured additive term basis matrices.

Basis

Basis matrix object.

StrctTerm.f

Alternative, more convenient constructor.

Notes

Note

The classes StrctInteractionTerm and StrctTensorProdTerm are closely related. The former loosely corresponds to mgcv::ti, and the latter loosely corresponds to mgcv::te, meaning that, when you supply centered marginals, StrctInteractionTerm will only include the highest-order interaction of the supplied marginals, while StrctTensorProdTerm will include the highest-order interaction and all lower-order interactions, including the main effects.

Assumes that the term is a tensor product of \(M\) marginal bases that can be written as

\[s(\mathbf{x}_i) = \sum_{j=1}^J B_j(\mathbf{x}_i)\beta_j = \mathbf{b}^\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 included in this term,

  • \(\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.

The vector of basis function evaluations is the Kronecker product of the marginal bases:

\[\mathbf{b}(\mathbf{x}_i)^\top = \mathbf{b}_1(x_{i,1})^\top \otimes \mathbf{b}_2(x_{i,2})^\top \otimes \cdots \otimes \mathbf{b}_M(x_{i,M})^\top,\]

In this notation, we assume that the marginal bases are often functions of just one covariate each, which is the common case. The individual terms have (potentially different) basis dimensions \(J_1, \dots, J_M\), such that the tensor product basis dimension is \(J = \prod_{m=1}^M J_m\).

The coefficient vector is equipped with a potentially rank-deficient multivariate Gaussian prior, which, in the notation of Bach & Klein (2025), can be written as

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

with the precision matrix constructed from marginal penalties \(\tilde{\mathbf{K}}_1, \dots, \tilde{\mathbf{K}}_M\) and variance parameters \(\tau^2_1,\dots, \tau^2_M\) as

\[\mathbf{K}(\boldsymbol{\tau}^2) = \frac{\mathbf{K}_1}{\tau^2_1} + \cdots + \frac{\mathbf{K}_M}{\tau^2_M},\]

where

\[\mathbf{K}_m = \mathbf{I}_{J_1} \otimes \cdots \otimes \mathbf{I}_{J_{m-1}} \otimes \tilde{\mathbf{K}}_m \otimes \mathbf{I}_{J_{m+1}} \otimes \cdots \mathbf{I}_{J_{M}},\]

and \(\mathbf{I}_{J_m}\) denotes the identity matrix of dimension \(J_m \times J_m\).

Since \(\mathbf{K}(\boldsymbol{\tau}^2)\) may be rank-deficient, \(\operatorname{Det}(\mathbf{K}(\boldsymbol{\tau}^2))\) is the pseudo-determinant, or generalized determinant.

This term exploits the clearly defined structure of the precision matrix to obtain a computationally and memory-efficient evaluation of the prior, implemented in the MultivariateNormalStructured distribution class. We also implement the results obtained by Bach & Klein (2025) for efficiently computing the pseudo-determinant; a key prerequisite for making higher-dimensional tensor products feasible.

References

  • Kneib, T., Klein, N., Lang, S., & Umlauf, N. (2019). Modular regression—A Lego system for building structured additive distributional regression models with tensor product interactions. TEST, 28(1), 1–39. https://doi.org/10.1007/s11749-019-00631-z

  • Bach, P., & Klein, N. (2025). Anisotropic multidimensional smoothing using Bayesian tensor product P-splines. Statistics and Computing, 35(2), 43. https://doi.org/10.1007/s11222-025-10569-y

Examples

>>> x = jnp.linspace(0.0, 1.0, 4)
>>> y = jnp.linspace(1.0, 2.0, 4)
>>> bx = Basis(
...     jnp.column_stack([jnp.ones_like(x), x]), xname="x", penalty=jnp.eye(2)
... )
>>> by = Basis(
...     jnp.column_stack([jnp.ones_like(y), y]), xname="y", penalty=jnp.eye(2)
... )
>>> sx = StrctTerm.f(bx, scale=1.0)
>>> sy = StrctTerm.f(by, scale=2.0)
>>> term = StrctInteractionTerm(sx, sy)
>>> term.basis.value.shape, term.coef.value.shape
((4, 4), (4,))

Methods

f

Alternative constructor with more opinionated automatic naming.

Attributes

input_obs

A dictionary of strong input variables.