penalty: Extract and tidy penalty matrices

In gavinsimpson/gratia: Graceful 'ggplot'-Based Graphics and Other Functions for GAMs Fitted Using 'mgcv'

Extract and tidy penalty matrices

Description

Extract and tidy penalty matrices

Usage

penalty(object, ...)

## Default S3 method:
penalty(
  object,
  rescale = FALSE,
  data,
  knots = NULL,
  constraints = FALSE,
  diagonalize = FALSE,
  ...
)

## S3 method for class 'gam'
penalty(
  object,
  select = NULL,
  smooth = deprecated(),
  rescale = FALSE,
  partial_match = FALSE,
  ...
)

## S3 method for class 'mgcv.smooth'
penalty(object, rescale = FALSE, ...)

## S3 method for class 'tensor.smooth'
penalty(object, margins = FALSE, ...)

## S3 method for class 't2.smooth'
penalty(object, margins = FALSE, ...)

## S3 method for class 're.smooth.spec'
penalty(object, data, ...)

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

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,

Note

The print() method uses base::zapsmall() to turn very small numbers into 0s for display purposes only; the underlying values of the penalty matrix or matrices are not changed.

For smooths that are subject to an eigendecomposition (e.g. the default thin plate regression splines, bs = "tp"), the signs of the eigenvectors are not defined and as such you can expect differences across systems in the penalties for such smooths that are system-, OS-, and CPU architecture- specific.

Author(s)

Gavin L. Simpson

Examples

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")

gavinsimpson/gratia documentation built on March 5, 2025, 10:01 a.m.