penalty: Extract and tidy penalty matrices

In 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, ...)

## S3 method for class 'gam'
penalty(object, smooth = NULL, rescale = 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.
smooth	character; vector of smooths to extract penalty matrices for. If NULL, penalty matrices for all smooths in object are extracted.
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.
margins	logical; extract the penalty matrices for the tensor product or the marginal smooths of the tensor product?
data	data frame; a data frame of values for terms mentioned in the smooth specification.

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, smooth = "s(x2):fac1")

gratia documentation built on Feb. 16, 2023, 10:40 p.m.