SmoothTerm

A smooth term, e.g. s(x1, bs='cr', k=10) or te(x1, x2).

Usage

Source

SmoothTerm(
    variables,
    smooth_type="s",
    bs="tp",
    k=-1,
    by=None,
    extra=dict(),
)

Represents an unspecified smooth function f(\cdot) of one or more covariates, entered into the model matrix as a spline basis expansion with an associated wiggliness penalty. The penalty’s strength (the smoothing parameter \lambda) is estimated automatically when the GAM is fit, rather than being a free choice like the degree of a polynomial term — this is what makes the term “smooth” in the GAM sense rather than a fixed parametric basis expansion.

smooth_type controls how multiple variables are combined:

  • "s": a single (marginal) smooth. Most common for one variable; for two or more it fits a single isotropic basis (e.g. a thin-plate spline over (x1, x2) jointly), appropriate when the covariates share the same scale/units.
  • "te": a full tensor-product smooth. Builds a separate marginal basis for each variable and forms their tensor (outer) product, with one smoothing parameter per marginal direction. Appropriate for interactions between covariates on different scales, and implicitly includes the main effects of each variable.
  • "ti": a tensor-product interaction smooth. Like "te", but each marginal’s penalty null space (e.g. the linear component) is projected out first, so the term captures only the pure interaction with no main-effect content. Used for an ANOVA-style decomposition, e.g. s(x1) + s(x2) + ti(x1, x2) separates main effects from their interaction.
  • "t2": an alternative tensor-product parameterization to "te", decomposing the penalty over every non-empty subset of the marginal directions (2^d - 1 penalties for d variables) so each interaction order gets its own smoothing parameter.

Parameters

variables: tuple[str, …]

Column names that are arguments to the smooth function. A single name for "s" (or two or more for a multivariate "s"); two or more names are required for "te", "ti", and "t2".

smooth_type: str = "s"

One of "s", "te", "ti", "t2" (see above). Defaults to "s".

bs: str = "tp"

Basis type. Common values include:

  • "tp" (default): thin plate regression spline — a good general-purpose default with no need to place knots.
  • "cr": cubic regression spline.
  • "cc": cyclic (periodic) cubic regression spline, for covariates such as day-of-year or angle where the ends of the range should meet smoothly.
  • "ps": P-spline (B-spline basis with a discrete difference penalty).
  • "cp": cyclic P-spline.
  • "ts" / "cs": shrinkage versions of "tp" / "cr" with an extra penalty on the null space, useful for automatic term selection without select=True.
  • "re": random-effect basis (one ridge-penalized column per factor level), for smooth-random-intercept terms.
  • "fs": factor-smooth interaction (a separate smooth per factor level, sharing one smoothing parameter).
  • "ad", "gp", "ds", "so", "mrf", "mpi"/"mpd", "cx"/"cv": adaptive, Gaussian-process, Duchon spline, soap-film, Markov-random-field, and monotone/convex-constrained bases respectively, for more specialized use cases.
k: int = -1

Number of basis functions (an upper bound on the effective degrees of freedom the smooth can use). -1 (default) means auto-select a sensible default for the basis type.

by: str or None = None

Name of a factor or numeric column for a factor-by smooth (a separate curve estimated per factor level) or a varying-coefficient smooth (the smooth’s value multiplies a numeric by column) — mirroring the by= argument in R’s mgcv.

extra: dict[str, Any] = dict()
Any additional keyword arguments passed through to the underlying basis constructor (e.g. xt=, m=), for basis types with extra configuration options.