SmoothInfo

Metadata describing where one smooth term lives inside a ModelMatrix.

Usage

SmoothInfo(
    term,
    basis,
    col_start,
    col_end,
    null_space_dim,
    penalty_indices=list(),
    by_var=None,
    by_level=None,
)

Each ~whittaker.formula.terms.SmoothTerm in a formula (an s(), te(), ti(), or t2() call) expands into several columns of the full design matrix X — one per basis function of the fitted SmoothBasis. A SmoothInfo records the bookkeeping needed to make sense of that expansion after the fact: which contiguous slice X[:, col_start:col_end] belongs to this term, the fitted SmoothBasis instance itself (so the exact same knots and constraints can be reused later), and which entries of ModelMatrix.penalties hold this term’s own penalty block(s). build_model_matrix creates one SmoothInfo per smooth term (or per by= level, for factor-by smooths) and stores the list on ModelMatrix.smooths; predict_matrix later reads these back to evaluate each smooth’s basis on new data without needing the original Formula object.

Attributes

term: SmoothTerm: The parsed SmoothTerm this info belongs to.
basis: SmoothBasis: The fitted SmoothBasis instance for this term. Retained so that predict_matrix can call basis.basis_matrix() on new covariate values using the exact knots, degrees of freedom, and identifiability constraints learned during fitting, rather than re-fitting a new basis.
col_start: int: Start column index (inclusive) in the full model matrix X.
col_end: int: End column index (exclusive) in the full model matrix X.
null_space_dim: int: Dimension of the penalty null space for this smooth, i.e. the number of basis directions (after identifiability constraints) that the penalty does not shrink at all. For an ordinary cubic or thin-plate spline this is typically the “linear” part of the smooth; for shrinkage bases (bs="ts", bs="cs") and random-effect/factor-smooth bases (bs="re", bs="fs") it is 0 because every direction is already penalized.
penalty_indices: list of int: Indices into ModelMatrix.penalties that belong to this smooth. For s() terms this is usually a single index (or two, if select=True added a null-space penalty); for te() terms it is one index per marginal direction.
by_var: str or None: Name of the by= variable for this term, or None if the term has no by= modifier.
by_level: str or None: For factor by= variables, the specific level this SmoothInfo corresponds to (one SmoothInfo is created per level); None for continuous by= variables or terms without a by= modifier.