TermBuilder.tf()

Contents

TermBuilder.tf()#

TermBuilder.tf(*marginals, common_scale=None, order=None, inference='default', scales_inference=MCMCSpec(<class 'liesel.goose.hmc.HMCKernel'>, self.kernel_group=None), prefix='', name=None, group_terms_by_order=False)[source]#

General full anisotropic tensor product term, including main effects and interactions.

Corresponds to mgcv::te.

Warning

This method removes any default gibbs samplers and replaces them with scales_inference on log level, since the full conditional for the variance parameters is not known in closed form for an anisotropic tensor product.

Parameters:

  • *marginals (StrctTerm) – Marginal terms, subclasses of StrctTerm.

  • common_scale (ScaleIG | Var | float | VarIGPrior | Literal['default'] | None, default: None) – A single, common scale to cover all marginal dimensions, resulting in an isotropic tensor product. This mean setting \(\tau^2_1 = \dots = \tau^2_M = \tau^2\) for all marginal smooths in the notation used in StrctInteractionTerm. Note that this will also change the scales of the supplied marginals (main effects).

  • order (Sequence[int] | None, default: None) – Sequence of intergers identifying the orders of interactions to be included in this term. For example, if you want to include only the bi- and trivariate interactions when supplying three marginals, pass order=(2,3). The default order=None means that all orders will be included; also the main effects.

  • inference (Any | None | Literal['default'], default: 'default') – Inference specification for this term’s coefficient. The default ("default") uses the TermBuilder’s default inference specification defined during initialization. Please refer to the TermBuilder documentation for more information.

  • scales_inference (Any | None | Literal['default'], default: MCMCSpec(<class 'liesel.goose.hmc.HMCKernel'>, self.kernel_group=None)) – If "default", uses the default inference passed to the TermBuilder upon initialization.

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

  • group_terms_by_order (bool, default: False) – If True, an intermediate variable object will be created for each order of interactions in this term. This can help to better organize the plotted graph of a term, but otherwise has no effect except using slightly more memory.

Return type:

StrctTensorProdTerm

Notes

Note

The methods tf() and tx() 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, tx will only include the highest-order interaction of the supplied marginals, while tf will include the highest-order interaction and all lower-order interactions, including the main effects.

See also

StrctTensorProdTerm

The term class returned by this method; includes further details.

tx

Tensor product interaction term, without main effects.

Examples

Using only the interaction term:

>>> import liesel_gam as gam
>>> df = gam.demo_data(100)

>>> tb = gam.TermBuilder.from_df(df)
>>> pred = gam.AdditivePredictor(name="loc")

>>> ps1 = tb.ps("x_nonlin", k=7)
>>> ps2 = tb.ps("x_lin", k=7)

>>> pred += tb.tf(ps1, ps2)
>>> pred.terms
{'tf(x_nonlin,x_lin)': StrctTensorProdTerm(name="tf(x_nonlin,x_lin)")}

To illustrate the difference to tx(), consider this example, which is practically equivalent:

>>> import liesel_gam as gam
>>> df = gam.demo_data(100)

>>> tb = gam.TermBuilder.from_df(df)
>>> pred = gam.AdditivePredictor(name="loc")

>>> ps1 = tb.ps("x_nonlin", k=7)
>>> ps2 = tb.ps("x_lin", k=7)

>>> pred += ps1, ps2, tb.tx(ps1, ps2)
>>> len(pred.terms)
3

Three-dimensional tensor product

>>> import liesel_gam as gam
>>> df = gam.demo_data(100)

>>> tb = gam.TermBuilder.from_df(df)
>>> pred = gam.AdditivePredictor(name="loc")

>>> pred += tb.tf(
...     tb.ps("x_nonlin", k=7),
...     tb.ps("x_lin", k=7),
...     tb.ps("x", k=7),
... )

>>> len(pred.terms)
1

The attribute StrctTensorProd.terms_by_order organizes the individual terms created by the full tensor product by interaction order. For example, these are the main effects:

>>> pred.terms["tf(x_nonlin,x_lin,x)"].terms_by_order[1]
[StrctTerm(name="ps(x_nonlin)"), ...]

These are the bivariate interactions:

>>> pred.terms["tf(x_nonlin,x_lin,x)"].terms_by_order[2]
[StrctInteractionTerm(name="tx(x_nonlin,x_lin)"), ...]

And this is the trivariate interaction:

>>> pred.terms["tf(x_nonlin,x_lin,x)"].terms_by_order[3]
[StrctInteractionTerm(name="tx(x_nonlin,x_lin,x)")]

We can inspect the number of coefficients in the trivariate interaction term:

>>> interaction = pred.terms["tf(x_nonlin,x_lin,x)"].terms_by_order[3]
>>> interaction[0]
StrctInteractionTerm(name="tx(x_nonlin,x_lin,x)")
>>> interaction[0].coef.value.shape
(216,)
Contents