onebasis: Generate a Basis Matrix for Different Functions
In gasparrini/dlnm: Distributed Lag Non-Linear Models

Description Usage Arguments Details Value Warnings Note Author(s) References See Also Examples

The function generates the basis matrix for a predictor vector. The function operates as a wrapper to existing or user-defined functions. Amongst other options, main choices include splines, polynomials, strata and linear threshold functions.

onebasis(x, fun="ns", ...)

## S3 method for class 'onebasis'
summary(object, ...)

`x`	the predictor variable. Missing values are allowed.
`fun`	character scalar with the name of the function to be called. See Details below.
`...`	additional arguments to be passed to the function specified by `fun` or to `summary`.
`object`	a object of class `"onebasis"`.

The function onebasis is a wrapper to existing functions which are called internally to produce different types of basis matrices in a pre-defined format. Its main use in the package dlnm is to be called by crossbasis to generate cross-basis matrices for modelling bi-dimensional exposure-lag-response associations in distributed lag linear (DLMs) and non-linear (DLNMs) models. However, it can be used also for simplifying the modelling and plotting of uni-dimensional exposure-response relationships.

The function to be called is chosen through the argument fun. Standard choices are:

"ns" and "bs": natural cubic B-splines or B-splines of various degree. Performed through a call to functions ns or bs from package splines. Arguments passed through ... may include df, knots, intercept, and Boundary.knots.
"ps" and "cr": penalized splines with different parameterizations and penalties. Performed through a call to functions ps or cr. Arguments passed through ... may include df, knots, degree, intercept, fx, S, and diff.
"poly": polynomials functions. Performed through a call to the internal function poly (be aware that this is different from poly in the package stats). Arguments passed through ... may include degree, scale and intercept.
"strata": indicator variables defining strata. Performed through a call to the function strata. Arguments passed through ... may include df, breaks, ref and intercept.
"thr": high, low or double linear threshold functions. Performed through a call to the function thr. Arguments passed through ... may include thr.value, side and intercept.
"integer": indicator variables for each integer value. Performed through a call to the internal function integer (be aware that this is different from the function integer in the package base). Arguments passed through ... may include intercept.
"lin": linear functions. Performed through a call to the internal function lin. Arguments passed through ... may include intercept.

The help pages of the called functions provides additional information. In particular, the option "lin" and "integer" are usually applied for defining constrained and unconstrained DLMs.

In addition, any other existing or user-defined function can be potentially called through onebasis. The function should have a first argument x defining the vector to be transformed. It also should return a vector or matrix of transformed variables, with attributes including the arguments of the function itself which define the transformations univocally.

A matrix object of class "onebasis" which can be included in a model formula in order to estimate the association. It contains the attributes fun, range (range of the original vector of observations) and additional attributes specific to the chosen function. The method summary.onebasis returns a summary of the basis matrix and the related attributes.

Meaningless combinations of arguments could lead to collinear variables, with identifiability problems in the model. The function onebasis does not perform many checks on the arguments provided. The user is expected to provide valid arguments.

This function offers a wide range of options about modelling the shape of the exposure-response relationships, also simplifying or extending the use of existing functions. The function crosspred can be called on objects of class "onebasis" in order to obtain predictions and plotting of such uni-dimensional associations. If more than one variable is transformed through onebasis in the same model, different names must be specified.

Before version 2.2.0 of dlnm, onebasis could include a cen argument for centering the basis. This step is now moved to the prediction stage, with a cen argument in crosspred or crossreduce (see the related help pages). For backward compatibility, the use of cen in onebasis is still allowed (with a warning), but may be discontinued in the future.

This function has replaced the two old functions mkbasis and mklagbasis since version 1.5.0.

Antonio Gasparrini <antonio.gasparrini@lshtm.ac.uk>

Gasparrini A. Distributed lag linear and non-linear models in R: the package dlnm. Journal of Statistical Software. 2011;43(8):1-20. [freely available here].

crossbasis to generate cross-basis matrices. crosspred to obtain predictions after model fitting. The method function plot to plot several type of graphs.

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

### a polynomial transformation of a simple vector
onebasis(1:5, "poly", degree=3)

### a low linear threshold parameterization, with and without intercept
onebasis(1:5, "thr", thr=3, side="l")
onebasis(1:5, "thr", thr=3, side="l", intercept=TRUE)

### relationship between PM10 and mortality estimated by a step function
b <- onebasis(chicagoNMMAPS$pm10, "strata", breaks=c(20,40))
summary(b)
model <- glm(death ~ b, family=quasipoisson(), chicagoNMMAPS)
pred <- crosspred(b, model, at=0:60)
plot(pred, xlab="PM10", ylab="RR", main="RR for PM10")

### changing the reference in prediction (alternative to argument ref in strata)
pred <- crosspred(b, model, cen=30, at=0:60)
plot(pred, xlab="PM10", ylab="RR", main="RR for PM10, alternative reference")

### relationship between temperature and mortality: double threshold
b <- onebasis(chicagoNMMAPS$temp, "thr", thr=c(10,25))
summary(b)
model <- glm(death ~ b, family=quasipoisson(), chicagoNMMAPS)
pred <- crosspred(b, model, by=1)
plot(pred, xlab="Temperature (C)", ylab="RR", main="RR for temperature")

### extending the example for the 'ns' function in package splines
b <- onebasis(women$height, df=5)
summary(b)
model <- lm(weight ~ b, data=women)
pred <- crosspred(b, model, cen=65)
plot(pred, xlab="Height (in)", ylab="Weight (lb) difference",
  main="Association between weight and height")
  
### use with a user-defined function with proper attributes
mylog <- function(x, scale=min(x, na.rm=TRUE)) {
  basis <- log(x-scale+1)
  attributes(basis)$scale <- scale
  return(basis)
}
mylog(-2:5)
onebasis(-2:5,"mylog")