dlnm (version 1.6.2)

crosspred: Generate Predictions for a DLNM

Description

Generate predictions from a distributed lag non-linear model (DLNM) for a set of values of the original predictor. Predictions are computed versus a reference predictor value, and interpreted as effects. Specific effects are computed for each combination of predictor and lag values, plus overall and (optionally) cumulative effects (summed up along lags). 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, 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.

at

vector of values used for prediction.

from, to

range of predictor values used for prediction.

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, cumulative effects are 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:
• predvar
  vector of observations used for prediction.
• lag
  integer vector defining the lag range.
• bylag
  increment of the sequence of lag values.
• coef, vcov
  coefficients and their variance-covariance matrix.
• matfit, matse
  matrices of predicted effects and related standard errors for each value of predvar and lag.
• allfit, allse
  vectors of overall predicted effects and related standard errors for each value of predvar.
• cumfit, cumse
  matrices of cumulative predicted effects (along lags) and related standard errors for each value of predvar and lag. Computed if cumul=TRUE.
• matRRfit
  matrix of exponentiated predicted effects from matfit.
• matRRlow, matRRhigh
  matrices with low and high confidence intervals for matRRfit.
• allRRfit
  vector of exponentiated overall predicted effects from allfit.
• allRRlow, allRRhigh
  vectors with low and high confidence intervals for allRRfit.
• cumRRfit
  matrix of exponentiated predicted effects from cumfit. Computed if cumul=TRUE.
• cumRRlow, cumRRhigh
  matrices with low and high confidence intervals for cumRRfit. Computed if cumul=TRUE.
• ci.level
  confidence level used for the computation of confidence intervals.
• model.class
  class of the model command used for estimation.
• model.link
  a 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 values for 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. bylag determines the lag step (forced to 1 for cumulative effects). 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 effects are returned. Exponentiated predicted effects 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 cumulative predicted effects summed upon lags for each values used for prediction are included if cumul=TRUE. For a long lag series (i.e. 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.jstatsoft.org/v43/i08/{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.ncbi.nlm.nih.gov/pubmed/20812303{here}]

See Also

onebasis to generate one-dimensional basis matrices. crossbasis to generate cross-basis matrices. crossreduce to reduce the fit to one dimension. plot.crosspred to plot several type of graphs. See dlnm-package for an overview of the package and type 'vignette(dlnmOverview)' for a detailed description.

Examples

### 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) + 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="Effects of 10-unit increase above the threshold (80CI)")
# PLOT THE OVERALL 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 effects over 5 days of lag")

# GET THE FIGURES FOR THE OVERALL 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