gratia (version 0.9.0)

penalty: Extract and tidy penalty matrices

Description

Extract and tidy penalty matrices

Usage

penalty(object, ...)
# S3 method for default
penalty(object, rescale = FALSE, data, knots = NULL, constraints = FALSE, ...)
# S3 method for gam
penalty(
  object,
  select = NULL,
  smooth = deprecated(),
  rescale = FALSE,
  partial_match = FALSE,
  ...
)
# S3 method for mgcv.smooth
penalty(object, rescale = FALSE, ...)
# S3 method for tensor.smooth
penalty(object, margins = FALSE, ...)
# S3 method for t2.smooth
penalty(object, margins = FALSE, ...)
# S3 method for re.smooth.spec
penalty(object, data, ...)

Value

A 'tibble' (data frame) of class penalty_df inheriting from tbl_df, with the following components:

• .smooth - character; the label mgcv uses to refer to the smooth,

• .type - character; the type of smooth,

• .penalty - character; the label for the specific penalty. Some smooths have multiple penalty matrices, so the penalty component identifies the particular penalty matrix and uses the labelling that mgcv uses internally,

• .row - character; a label of the form fn where n is an integer for the nth basis function, referencing the columns of the penalty matrix,

• .col - character; a label of the form fn where n is an integer for the nth basis function, referencing the columns of the penalty matrix,

• .value - double; the value of the penalty matrix for the combination of row and col,

Arguments

object

a fitted GAM or a smooth.

...

additional arguments passed to methods.

rescale

logical; by default, mgcv will scale the penalty matrix for better performance in mgcv::gamm(). If rescale is TRUE, this scaling will be undone to put the penalty matrix back on the original scale.

data

data frame; a data frame of values for terms mentioned in the smooth specification.

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().

select

character, logical, or numeric; which smooths to extract penalties for. If NULL, the default, then penalties for all model smooths are drawn. Numeric select indexes the smooths in the order they are specified in the formula and stored in object. Character select matches the labels for smooths as shown for example in the output from summary(object). Logical select operates as per numeric select in the order that smooths are stored.

smooth

Use select instead.

partial_match

logical; should smooths be selected by partial matches with select? If TRUE, select can only be a single string to match against.

margins

logical; extract the penalty matrices for the tensor product or the marginal smooths of the tensor product?

Author

Gavin L. Simpson

Examples

# \dontshow{
op <- options(cli.unicode = FALSE, pillar.sigfig = 3)
# }
load_mgcv()
dat <- data_sim("eg4", n = 400, seed = 42)
m <- gam(
  y ~ s(x0, bs = "cr") + s(x1, bs = "cr") +
    s(x2, by = fac, bs = "cr"),
  data = dat, method = "REML"
)

# penalties for all smooths
penalty(m)

# for a specific smooth
penalty(m, select = "s(x2):fac1")

# \dontshow{
options(op)
# }