cr {dlnm}

Generate a Basis Matrix for Penalized Cubic Regression Splines

Description

Generate the basis matrix for cubic regression splines with penalties on the second derivatives.

Usage

cr(x, df=10, knots=NULL, intercept=FALSE, fx= FALSE, S=NULL)

Arguments

x

the predictor variable. Missing values are allowed.

df

degrees of freedom, basically the dimension of the basis matrix. If supplied in the absence of knots, it automatically selects df+1-intercept knots at equally-spaced quantiles of x. The minimum allowed is df=3.

knots

breakpoints that define the spline. These are generally automatically selected, and not defined by the user. See Details below.

intercept

logical. If TRUE, an intercept is included in the basis matrix. See Details below.

fx

logical. If TRUE, it removes the penalization. See Details below.

S

penalty matrix, usually internally defined if NULL (default).

Details

The function has a usage similar to bs and ns in the splines package. It produces spline transformations, however using a parameterization that represents the splines fit in terms of values at the knots. A penalty matrix is also defined. The same results are returned by the related smooth constructor in the package mgcv, which is in fact called internally.

The argument knots defines a vector of knots within the range of the predictor x, by default at equally-spaced quantiles. The penalization is defined on the second derivative of the function through a penalty matrix S.

Similarly to bs and ns, setting intercept=FALSE (default) determines the exclusion of the first transformed variables, and the corresponding first row and column in S, thus avoiding identifiability issues during the model fitting. Note how the procedure of imposing identifiability constraints is different from that adopted by smoothCon in the package mgcv, where a more complex reparameterization is produced.

Value

A matrix object of class "cr". It contains the attributes df, knots, intercept, fx, and S, with values that can be different than the arguments provided due to internal reset.

Note

The function is primarily added here to specify penalized DLMs and DLNMs using the so-called external method, i.e. by including the penalty matrix in the argument paraPen of the gam regression function in mgcv (see cbPen). However, this approach can be also used to fit standard uni-dimensional penalized cubic spline models as an alternative to the use of specific smooth constructor, as it takes advantage of the use of prediction and plotting functions in dlnm.

Author(s)

Antonio Gasparrini <[e-mail]>, with internall calls to functions included in the package mgcv by Simon N. Wood.

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

ps for P-splines. bs and ns for B-splines and natural cubic splines, respectively. cbPen for defining tensor-type bi-dimensional penalties in DLNMs. The related smooth constructor for cubic regression spline smooths in mgcv. The cb smooth constructor for cross-basis penalized spline smooths.

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

Examples

# to be added soon