crosspred: Generate Predictions for a DLNM

Description

The function generates predictions from a distributed lag non-linear model (DLNM). These are interpreted as estimated associations defined on a grid of values of the original predictor and lags, computed versus a reference predictor value. Specifically, predictor-specific associations expressed along the lag space, lag-specific associations expressed along the predictor space, and the overall cumulative association on the whole lag period. The function can be used also for simple basis functions not including lag.

Usage

crosspred(basis, model=NULL, coef=NULL, vcov=NULL, model.link=NULL, at=NULL,
  from=NULL, to=NULL, by=NULL, lag, bylag=1, ci.level=0.95, cumul=FALSE)

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

Arguments

basis

an object of class "onebasis" or "crossbasis".

model

a model object for which the prediction is desired. See Details below.

coef, vcov, model.link

user-provided coefficients, (co)variance matrix and model link for the prediction. See Details below.

vector of predictor values used for prediction.

from, to

range of predictor values used for prediction.

lag

either an integer scalar or vector of length 2, defining the lag range used for prediction. Defalut to values used for estimation.

by, bylag

increment of the sequences of predictor and lag values used for prediction.

ci.level

confidence level for the computation of confidence intervals.

cumul

logical. If TRUE, incremental cumulative associations along lags are also predicted. See Details.

object

an object of class "crosspred".

...

additional arguments to be passed to summary.

Value

A list object of class "crosspred" with the following (optional) components:
predvarvector of observations used for prediction.
laginteger vector defining the lag range used for prediction.
bylagincrement of the sequence of lag values.
coefficients, vcovcoefficients and their variance-covariance matrix.
matfit, matsematrices of specific predicted associations and related standard errors at each value of predvar and lag.
allfit, allsevectors of the overall cumulative predicted association and related standard errors at each value of predvar in the chosen lag period.
cumfit, cumsematrices of incremental cumulative predicted associations along lags and related standard errors at each value of predvar and lag. Computed if cumul=TRUE.
matRRfitmatrix of exponentiated specific associations from matfit.
matRRlow, matRRhighmatrices with low and high confidence intervals for matRRfit.
allRRfitvector of exponentiated overall cumulative associations from allfit.
allRRlow, allRRhighvectors with low and high confidence intervals for allRRfit.
cumRRfitmatrix of exponentiated incremental cumulative associations from cumfit. Computed if cumul=TRUE.
cumRRlow, cumRRhighmatrices with low and high confidence intervals for cumRRfit. Computed if cumul=TRUE and if lag[1] is equal to 0.
ci.levelconfidence level used for the computation of confidence intervals.
model.classclass of the model command used for estimation.
model.linka specification for the model link function.
The function summary.crosspred returns a summary of the list.

Warnings

In case of collinear variables in the basis object, some of them are discarded and the related parameters not included in model. Then, crosspred will return an error. Check that the specification of the variables is meaningful through summary.crossbasis or summary.onebasis. The name of the object basis will be used to extract the related estimated parameters from model. If more than one variable is transformed by cross-basis functions in the same model, different names must be specified.

Details

model is the model object including basis. It must include methods for coef and vcov, applied to extract the parameters. For model classes without these methods, the user can manually extract the related parameters and include them in coef-vcov, also specifying model.link. In this case, the dimensions and order of the first two must match the variables included in basis. The object basis must be the same containing the basis or cross-basis matrix included in model, preserving its attributes and class. The set of predictor values at which predictions must be computed can be specified by at or alternatively by from/to/by. If specified by at, the values are automatically ordered and made unique. If at and by are not provided, approximately 50 equally-spaced rounded values are returned using pretty. lag defines the lag values used for prediction, while bylag determines the lag step (forced to 1 for incremental cumulative associations). The function can be used to compute predictions for models with simple basis functions not including lag, computed with onebasis. In this case, only unlagged predicted associations are returned. Exponentiated predictions are included if model.link is equal to log or logit, together with confidence intervals computed using a normal approximation and a confidence level of ci.level. model.link is automatically selected from model for classes "lm"-"glm"-"gam"-"clogit"-"coxph", but needs to be provided for different classes. Matrices with incremental cumulative predicted associations along lags at each values used for prediction are included if cumul=TRUE and if lag[1] is equal to 0. For a long lag series (e.g. 1000 lags) the routine can be slow. For a detailed illustration of the use of the functions, see: vignette("dlnmOverview")

References

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 http://www.ag-myresearch.com/jss2011.html{here}]. Gasparrini A., Armstrong, B.,Kenward M. G. Distributed lag non-linear models. Statistics in Medicine. 2010; 29(21):2224-2234. [freely available http://www.ag-myresearch.com/statmed2010{here}]

Examples

Run this code

### seasonal analysis
### space of predictor: linear effect above 40.3 microgr/m3 for O3
### space of predictor: linear effects below 15C and above 25C for temperature
### lag function: integer lag parameterization (unconstrained) for O3 up to lag5
### lag function: strata intervals at lag 0-1, 2-5 and 6-10 for temperature

# SELECT SUMMER MONTHS OF THE SERIES
chicagoNMMAPSseas <- subset(chicagoNMMAPS, month>5 & month<10)

# CREATE THE CROSS-BASIS FOR EACH PREDICTOR, SPECIFYING THE GROUP VARIABLE
cb2.o3 <- crossbasis(chicagoNMMAPSseas$o3, lag=5, argvar=list(type="hthr",
  knots=40.3), arglag=list(type="integer"), group=chicagoNMMAPSseas$year)
cb2.temp <- crossbasis(chicagoNMMAPSseas$temp, lag=10,
  argvar=list(type="dthr",knots=c(15,25)), arglag=list(type="strata",
  knots=c(2,6)), group=chicagoNMMAPSseas$year)
summary(cb2.o3)
summary(cb2.temp)

# RUN THE MODEL AND GET THE PREDICTION FOR 03
library(splines)
model2 <- glm(death ~  cb2.o3 + cb2.temp + ns(doy, 4) + ns(year,3) + dow,
  family=quasipoisson(), chicagoNMMAPSseas)
pred2.o3 <- crosspred(cb2.o3, model2, at=c(0:65,40.3,50.3))

# PLOT THE LINEAR ASSOCIATION OF 03 ALONG LAGS (WITH 80%CI)
plot(pred2.o3, "slices", var=50.3, ci="bars", type="p", pch=19, ci.level=0.80,
  main="Association with a 10-unit increase above threshold (80CI)")
# PLOT THE OVERALL CUMULATIVE ASSOCIATION
plot(pred2.o3,"overall",xlab="Ozone", ci="lines", ylim=c(0.9,1.3), lwd=2,
  ci.arg=list(col=1,lty=3), main="Overall cumulative association for 5 lags")

# GET THE FIGURES FOR THE OVERALL CUMULATIVE ASSOCIATION ABOVE, WITH CI
pred2.o3$allRRfit["50.3"]
cbind(pred2.o3$allRRlow, pred2.o3$allRRhigh)["50.3",]

# 3-D PLOT WITH DEFAULT AND USER-DEFINED PERSPECTIVE
plot(pred2.o3, xlab="Ozone", main="3D: default perspective")
plot(pred2.o3, xlab="Ozone", main="3D: different perspective", theta=250, phi=40)
### See the vignette 'dlnmOverview' for a detailed explanation of this example

Run the code above in your browser using DataLab