ps: Generate a Basis Matrix for P-Splines

In dlnm: Distributed Lag Non-Linear Models

Description

Generate the basis matrix for P-splines, namely a B-spline basis with difference penalties.

Usage

ps(x, df=10, knots=NULL, degree=3, intercept=FALSE, fx= FALSE, S=NULL, diff=2)

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+degree+2-intercept equally-spaced knots (within and beyond the range of x). The minimum df allowed is degree+1-intercept.
knots	breakpoints that define the spline. These are generally automatically selected, and not defined by the user. See Details below.
degree	degree of the piecewise polynomial. Default is 3 for cubic splines.
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).
diff	order difference of the penalty.

Details

The function has a usage similar to bs and ns in the splines package. It produces B-spline transformations through a call to splineDesign, plus a difference matrix to define penalties. The same results are returned by the related smooth constructor in the package mgcv.

The argument knots defines a vector of knots or (if of length 2) the lower and upper limits between which the splines can be evaluated. However, knots should be usually left automatically selected, and in particular these P-splines only have sense with equally-spaced knots, due to the nature of the penalization. It is important to highlight that, differently from bs where internal and boundary knots are defined, this function adopts a standard B-spline parameterization, including by default 2*(degree+1) knots beyond the range of the variable.

The penalization is defined on the difference of adjacent coefficients during fitting procedure through a penalty matrix S. The argument diff selects the order difference (with the default 2 determining a second order difference, and 0 producing a ridge penalty), while setting fx=TRUE removes the penalization.

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 "ps". It contains the attributes df, knots, degree, intercept, fx, S, and diff, 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 P-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]>, adapting code available from 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]

Eilers P. H. C. and Marx B. D. Flexible smoothing with B-splines and penalties. Statistical Science. 1996;11(2):89-121.

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

See Also

cr for penalized cubic regression 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 P-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

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.