Basis expansions for smooths

Basis expansions from a definition of a smoother using the syntax of mgcv's smooths via mgcv::s()., mgcv::te(), mgcv::ti(), and mgcv::t2(), or directly from a fitted GAM(M).

Usage

basis(object, ...)

# S3 method for class 'gam'
basis(
  object,
  select = NULL,
  term = deprecated(),
  data = NULL,
  n = 100,
  n_2d = 50,
  n_3d = 16,
  n_4d = 4,
  partial_match = FALSE,
  envir = NULL,
  ...,
  variables = NULL,
  unweighted = FALSE
)

# S3 method for class 'scam'
basis(
  object,
  select = NULL,
  term = deprecated(),
  data = NULL,
  n = 100,
  n_2d = 50,
  n_3d = 16,
  n_4d = 4,
  partial_match = FALSE,
  ...,
  variables = NULL,
  unweighted = FALSE
)

# S3 method for class 'gamm'
basis(
  object,
  select = NULL,
  term = deprecated(),
  data = NULL,
  n = 100,
  n_2d = 50,
  n_3d = 16,
  n_4d = 4,
  partial_match = FALSE,
  ...,
  variables = NULL,
  unweighted = FALSE
)

# S3 method for class 'gamm4'
basis(
  object,
  select = NULL,
  term = deprecated(),
  data = NULL,
  n = 100,
  n_2d = 50,
  n_3d = 16,
  n_4d = 4,
  partial_match = FALSE,
  ...,
  variables = NULL,
  unweighted = FALSE
)

# Default S3 method
basis(
  object,
  data,
  knots = NULL,
  constraints = FALSE,
  at = NULL,
  diagonalize = FALSE,
  coefficients = NULL,
  envir = NULL,
  ...,
  variables = NULL
)

Arguments

object

a smooth specification, the result of a call to one of mgcv::s()., mgcv::te(), mgcv::ti(), or mgcv::t2(), or a fitted GAM(M) model.

...

other arguments passed to mgcv::smoothCon().

select

character; select smooths in a fitted model

term

This argument has been renamed select

data

a data frame containing the variables used in smooth.

n

numeric; the number of points over the range of the covariate at which to evaluate a univariate smooth.

n_2d

numeric; the number of points along each of the first two axes of a smooth surface, including surface panels of higher-dimensional smooths. The default is 50 in plotting and plot-preparation functions. If NULL, use n instead. Ignored when evaluation data are supplied. Factor levels are retained, and curves with only one continuous covariate use n.

n_3d

numeric; the number of new observations to generate for the third dimension of a 3D smooth.

n_4d

numeric; the number of new observations to generate for the dimensions higher than 2 (!) of a kD smooth (k >= 4). For example, if the smooth is a 4D smooth, each of dimensions 3 and 4 will get n_4d new observations.

partial_match

logical; in the case of character select, should select match partially against smooths? If partial_match = TRUE, select must only be a single string, a character vector of length 1.

envir

an optional environment supplying functions and constants used in model expressions. The available model formula environment is used when NULL. Covariate observations should be supplied in data.

variables

character; smooth covariates in plotting order. Supply every covariate exactly once. The first two define surface axes and the remaining covariates define conditioning facets. Selected smooths must have the same covariates. If NULL, use the usual smooth plotting order.

unweighted

logical; for fitted models, return basis functions without multiplying by fitted coefficients? The default, FALSE, returns the coefficient-weighted contributions. With TRUE, draw() shows the shared basis once for each factor-by set.

knots

a list or data frame with named components containing knots locations. Names must match the covariates for which the basis is required. See mgcv::smoothCon().

constraints

logical; should identifiability constraints be applied to the smooth basis. See argument absorb.cons in mgcv::smoothCon().

at

a data frame containing values of the smooth covariate(s) at which the basis should be evaluated.

diagonalize

logical; if TRUE, reparameterises the smooth such that the associated penalty is an identity matrix. This has the effect of turning the last diagonal elements of the penalty to zero, which highlights the penalty null space.

coefficients

numeric; vector of values for the coefficients of the basis functions.

Value

A tibble with class basis. Its plot_variables attribute stores covariate orders by smooth label for subsequent plotting. When the basis is shared across factor levels, factor_by_groups records the smooth labels that draw() combines. The returned rows retain each level.

Details

When evaluating a fitted smooth at explicit data, missing covariates required by that smooth produce NA basis values. Missing values in other model variables do not discard otherwise evaluable rows. The covariate order chosen by variables also determines which automatically generated axes use n_2d, n_3d, and n_4d. Supplied data or at values are unchanged. Set a resolution argument to NULL to use n instead.

Author

Gavin L. Simpson

Examples

load_mgcv()
df <- data_sim("eg4", n = 400, seed = 42)

bf <- basis(s(x0), data = df)
bf <- basis(s(x2, by = fac, bs = "bs"), data = df, constraints = TRUE)