crosspred: Generate predicted effects for a DLNM

Description

Generate predicted effects from a distributed lag non-linear model (DLNM) for a set of values of the original predictor. It returns specific effects for each combination of values and lags, plus overall and (optionally) cumulative effects (summed up along lags).

Usage

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

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

Arguments

basis

an object of class "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 values used for prediction.

from, to, by

range of values and increment of the sequence used for prediction.

ci.level

confidence level for the computation of confidence intervals.

cumul

logical. If TRUE, cumulative effects are predicted. See Details.

object

a object of class "crosspred".

...

additional arguments to be passed to summary.

Value

A list object of class "crosspred" with the following components:
predvarvector of observations used for prediction.
maxlaga positive value defining the maximum lag.
coef, vcovcoefficients and their variance-covariance matrix.
matfit, matsematrices of effects and related standard errors for each value of predvar and lag.
allfit, allsevectors of total effects and related standard errors for each value of predvar.
cumfit, cumsematrices of cumulative effects (along lags) and related standard errors for each value of predvar and lag. Computed if cumul=TRUE.
matRRfitmatrix of exponentiated effects from matfit.
matRRlow, matRRhighmatrices with low and high confidence intervals for matRRfit.
allRRfitvector of exponentiated total effects from allfit.
allRRlow, allRRhighvectors with low and high confidence intervals for allRRfit.
cumRRfitmatrix of exponentiated effects from cumfit. Computed if cumul=TRUE.
cumRRlow, cumRRhighmatrices with low and high confidence intervals for cumRRfit. Computed if cumul=TRUE.
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 . The name of the object crossbasis 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, used to fit the DLNM. 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 cross-basis matrix included in model, including its attributes and class. The set of values for which the effects 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. Exponentiated 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 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. URL http://www.jstatsoft.org/v43/i08/. Gasparrini A., Armstrong, B.,Kenward M. G. Distributed lag non-linear models. Statistics in Medicine. 2010; 29(21):2224-2234.

Examples

Run this code

# Example 2. See crossbasis and plot.crosspred for other 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
basis.o3 <- crossbasis(chicagoNMMAPSseas$o3, group=chicagoNMMAPSseas$year,
	vartype="hthr", varknots=40.3, lagtype="integer", maxlag=5)
basis.temp <- crossbasis(chicagoNMMAPSseas$temp, group=chicagoNMMAPSseas$year,
	vartype="dthr", varknots=c(15,25), lagtype="strata",
	lagknots=c(2,6), maxlag=10)
summary(basis.o3)
summary(basis.temp)

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

# PLOT THE LINEAR EFFECTS OF 03 ABOVE THE THRESHOLD (WITH 80%CI)
plot(pred.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(pred.o3,"overall",xlab="Ozone", ci="lines", ylim=c(0.9,1.3), lwd=2,
	ci.arg=list(col=1,lty=3), main="Overall effect over 5 days of lag")

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

# 3-D PLOT WITH DEFAULT AND USER-DEFINED PERSPECTIVE
plot(pred.o3, xlab="Ozone", main="3D graph of ozone effect")
plot(pred.o3, xlab="Ozone", main="3D graph of ozone effect", theta=250, phi=40)

### See the vignette 'dlnmOverview' for a detailed explanation of this example

Run the code above in your browser using DataLab