TermBuilder.f()

Contents

TermBuilder.f()#

TermBuilder.f(*x, basis_fn, scale='default', inference='default', use_callback=True, cache_basis=True, penalty=None, factor_scale=False, prefix='', name=None)[source]#

General StrctTerm, initialized by passing a custom basis function.

Note

You can use StrctTerm.constrain() to apply linear constraints to your custom term.

Parameters:

  • *x (str | Var) – Variable number of input variable names. Can be one or more.

  • basis_fn (Callable[[Array], Array]) – Basis function. Must take a 2d-array as input and return a 2d array.

  • scale (ScaleIG | Var | float | VarIGPrior | Literal['default'], default: 'default') –

    Scale parameter passed to the coefficient prior, StrctTerm.scale.

    • If "default", the scale will be initialized according to the default scale function defined for this TermBuilder instance. Please refer to the TermBuilder documentation for more information.

    • If you pass a float, this will be taken as the constant value of the scale, and the scale will not be estimated as part of the model without further action.

    • If you pass a liesel.model.Var, this will be used as the scale. Make sure to define the inference attribute of your custom scale variable (or a latent, transformed version of it).

    • If you pass a VarIGPrior, a scale variable will be set up for you using ScaleIG. This means, the scale will be \(\tau\), with an iverse Gamma prior on its square, i.e. \(\tau^2 \sim \operatorname{InverseGamma}(a, b)\), where a and b are taken from the VarIGPrior object. A fitting Gibbs kernel will be set up automatically to sample \(\tau^2\) in this case, see ScaleIG for details.

  • inference (Any | None | Literal['default'], default: 'default') – Inference specification for this term’s coefficient. Note that this inference is only used for the coefficient variables of the terms created by this builder (StrctTerm.coef), not for the scale variables (StrctTerm.scale). The default ("default") uses the TermBuilder’s default inference specification defined during initialization. Please refer to the TermBuilder documentation for more information.

  • use_callback (bool, default: True) – If True, the basis function is evaluated using a Python callback, which means that it does not have to be jit-compatible via JAX. This also means that the basis must remain constant throughout estimation. Passed on to Basis.

  • cache_basis (bool, default: True) – If True the computed basis is cached in a persistent calculation node (lsl.Calc), which avoids re-computation when not required. Passed on to Basis.

  • factor_scale (bool, default: False) – Whether to factor out the scale in the prior for this term, turning it into a partially (or fully) standardized form. See StrctTerm.factor_scale() for details.

  • prefix (str, default: '') – A string prefix to be added to the returned term’s name.

  • name (str | None, default: None) – Manually defined name of the term. If a prefix is specified, the prefix will be added to this name.

See also

StrctTerm.constrain

Apply constraints to a term after initialization.

StrctTerm.diagonalize_penalty

Diagonalize the penalty of a term after initialization.

StrctTerm.scale_penalty

Scale the penalty of a term after initialization.

BasisBuilder.basis

Used by this method to set up the basis.

Return type:

StrctTerm

Examples

Manually set up a P-spline:

>>> from liesel.contrib.splines import (
...     basis_matrix,
...     equidistant_knots,
...     pspline_penalty,
... )
>>> import liesel_gam as gam

>>> df = gam.demo_data(n=100)
>>> tb = gam.TermBuilder.from_df(df)

Set up basis function:

>>> knots = equidistant_knots(df["x_nonlin"].to_numpy(), n_param=20)
>>> pen = pspline_penalty(d=20)
>>> def bspline_basis(x_mat):
...     # x_mat is shape (n, 1)
...     x_vec = x_mat.squeeze()  # shape (n,)
...     return basis_matrix(x_vec, knots=knots)

Initialize the term:

>>> fx = tb.f("x_nonlin", basis_fn=bspline_basis, penalty=pen)

The term currently has a basis of dimension (100, 20), since it is unconstrained.

>>> fx.basis.value.shape
(100, 20)

You can use StrctTerm.constrain() to apply a constraint:

>>> fx.constrain("sumzero_term")
StrctTerm(name="f(x_nonlin)")

Now the basis dimension is reduced:

>>> fx.basis.value.shape
(100, 19)
Contents