smooth.construct.cb.smooth.spec: Cross-Basis Spline Smooths for a DLNM

In dlnm: Distributed Lag Non-Linear Models

Description

These are method functions for a smooth class defining bi-dimensional cross-basis splines for penalized distributed lag linear (DLMs) and non-linear (DLNMs) models. The functions are not supposed to be called directly, and the class is usually specified via terms like s(X,L,bs="cb",...) in the formula of the gam function of the package mgcv.

Usage

## S3 method for class 'cb.smooth.spec'
smooth.construct(object, data, knots)

## S3 method for class 'cb.smooth'
Predict.matrix(object, data)

Arguments

object	for smooth.construct, an object of class "cb.smooth.spec" usually generated by a call s(X,L,bs="cb",...). For Predict.matrix, an object of class cb.smooth generated by smooth.construct.
data	a list containing just the data (including any by variable) required by this term, with names corresponding to object$term.
knots	a list containing any knots supplied for basis setup — in same order and with same names as data. It is usually NULL.

Details

These method functions embed tools available in the packages dlnm and mgcv to perform penalized DLMs and DLNMs. This represent the internal approach to perform such models (see Notes below). Specifically, the models are fitted by including a term s(X,L,bs="cb",...), defining a basis "cb" for bi-dimensional cross-basis splines, in the formula of the gam function. The constructor function for this class turns this smooth terms into a smooth specification object, which includes the cross-basis matrix (see crossbasis) and the penalty matrices for the two spaces of predictor and lags used in model fitting. Then, crosspred uses the predict matrix function for the "cb" basis to obtain predictions, and a graphical representation can be obtained by standard plotting functions, similary to unpenalized models.

The first two arguments X and L in s represent a matrix of exposure histories and a matrix of lags. The former, also used in crossbasis, needs to be defined directly even with time series data by lagging the exposure series. The matrix L must have the same dimensions of X, with identical rows representing the sequence of lags. The other arguments of s have the same meaning: in particular, k (default to 10), fx (default to FALSE) and sp (default to NULL) can be provided for each marginal basis as vectors of length 2, and similarly m can be provided as a list (see also te). No by argument is allowed.

Extra information can be included in the argument xt of s, which accepts a single object or a list of objects. First, an object bs (a vector of length 1 or 2) can be used to specify the smoother for each marginal dimension, with current options restricted to "ps" (P-splines, used by default) and/or "cr" (cubic regression splines). Second, list objects argvar and arglag can be used to build the marginal bases for predictor and lags by calling other functions (see the same arguments in crossbasis). In particular, these can be used for a more flexible specification of penalized functions (using ps or cr) or for using unpenalized functions for one marginal basis, thus limiting the penalization to one of the two dimensions. Third, the object addSlag can contain a matrix or vector (or list of matrices and/or vectors) defining additional penalties on the lag structure (see cbPen).

Value

The smooth constructor function returns an object of classes "cb.smooth" and "tensor.smooth". Specifically, a list with a similar structure of that returned by the smooth constructor for tensor product smooths (see also te).

The Predict.matrix function return a cross-basis matrix evaluated at specific values used for prediction.

Note

Identifiability constraints are applied to marginal basis for predictor (see smoothCon), while the marginal basis for the lag dimension is left untransformed. This involves a re-parameterization with the absorption of constraints into the basis that causes its dimension to decrease by 1. Note that this procedure is similar to that in crossbasis, while it is different than in standard tensor product smooths (see te), where identifiability constraints are not applied to the marginal bases.

Using the default specification with k=10 in the smooth terms defined by s, the dimension of the cross-basis matrix will be (10-1)x10=90 (accounting for identifiability constraints). This is consistent with the rationale that this choice is not important as far as the upper limit for the degrees of freedom in each marginal basis is large enough to represent the underlying relationship (see choose.k). Smaller values of k can be used for speeding up the computation, as long as the underlying relationship can be assumed to be smooth enough.

These method functions provide an internal method for performing penalized DLMs and DLNMs, with the cross-basis spline smoother defined directly in the model formula of gam through a smooth term specified by s. The alternative external method relies on the standard use of crossbasis and on the penalization of so-called parametric terms through the argument paraPen of gam (see cbPen for details). The two methods are expected to returns almost identical results in most cases. However, while the internal method takes advantage of the full machinery of mgcv and plausibly more stable procedures, the external method allows more flexibility and the optional use of user-defined smoothers.

Author(s)

Antonio Gasparrini <[e-mail]> and Fabian Scheipl <[e-mail]>

References

Gasparrini A, Scheipl F, Armstrong B, Kenward MG. A penalized framework for distributed lag non-linear models. Biometrics. 2017;73(3):938-948. [freely available here]

Wood S. N. Generalized Additive Models: An Introduction with R. Chapman and Hall/CRC Press, 2006.

See Also

Smooth constructors for P-splines and cubic regression splines in mgcv. ps and cr for the same functions available in dlnm. cbPen for defining tensor-type bi-dimensional penalties in DLNMs.

See dlnm-package for an introduction to the package and for links to package vignettes providing more detailed information.

Examples

# to be added soon

Example output

This is dlnm 2.3.9. For details: help(dlnm) and vignette('dlnmOverview').

dlnm documentation built on Oct. 7, 2021, 5:09 p.m.