JM (version 1.5-2)

residuals: Residuals for Joint Models

Description

Calculates residuals for joint models.

Usage

# S3 method for jointModel
residuals(object, process = c("Longitudinal", "Event"), 
  type = c("Marginal", "Subject", "stand-Marginal", 
  "stand-Subject", "Martingale", "nullMartingale", "CoxSnell", "AFT"), 
  MI = FALSE, M = 50, time.points = NULL, return.data = FALSE, 
  ...)

Value

If MI = FALSE, a numeric vector of residual values. Otherwise a list with components:

fitted.values

the fitted values for the observed data.

residuals

the residuals for the observed data.

fitted.valsM

the fitted values for the missing data.

resid.valsM

the multiply imputed residuals for the missing longitudinal responses.

mean.resid.valsM

the average of the multiply imputed residuals for the missing longitudinal responses; returned only if fixed visit times are considered.

dataM

if return.data = TRUE and fixed visit times are considered, then it returns the data set with the simulated response values for the longitudinal outcome, for each of the multiple imputations.

Arguments

object

an object inheriting from class jointModel.

process

for which model (i.e., linear mixed model or survival model) to calculate residuals.

type

what type of residuals to calculate. See Details.

MI

logical; if TRUE multiple-imputation-based residuals are calculated.

M

integer denoting how many imputations to use for the MI residuals.

time.points

for fixed visit times, this should be a numeric vector with the unique times points at which longitudinal measurements are supposed to be taken; if NULL, then the code attempts to extract these unique time points using the design matrix for the fixed effects of the longitudinal model and the value of the timeVar argument of jointModel. For random visit times, this should be an object of class weibull.frailty that represents the fit of Weibull model with Gamma frailties for the visiting process. The user may also augment the object weibull.frailty with the following two attributes: "prev.y" denoting the variable name for the previous longitudinal responses, and "tmax" denoting the end of the study.

return.data

logical; if TRUE and MI = TRUE and fixed visit times are considered, then the multiply imputed data sets are returned.

...

additional arguments; currently none is used.

Author

Dimitris Rizopoulos

Details

When process = "Longitudinal", residuals are calculated for the longitudinal outcomes. In particular, if type = "Marginal" these are \(e_{ij} = y_{ij} - x_{ij}^T \hat{\beta}\), whereas for type = "Subject", \(e_{ij} = y_{ij} - x_{ij}^T \hat{\beta} - z_{ij}^T b_i\), where \(i\) denotes the subject and \(j\) the measurement, \(y_{ij}\) the longitudinal responses, \(x_{ij}^T\) and \(z_{ij}^T\) the corresponding rows of the fixed and random effects design matrices, respectively, and \(\beta\) and \(b_i\) denote the fixed effects and random effects components. If type = "stand-Marginal" or type = "stand-Subject", the above defined residuals are divided by the estimated standard deviation of the corresponding error term. If MI = TRUE, multiple-imputation-based residuals are calculated for the longitudinal process; for more information regarding these residuals, check Rizopoulos et al. (2009).

When process = "Event", residuals are calculated for the survival outcome. Martingale residuals are available for all options for the survival submodel (for the different options of survival submodel, check the method argument of jointModel). when option type = "nullMartingale" is invoked, the martingale residuals are calculated with the coefficient(s) that correspond to the marker set to zero. Cox-Snell residuals (Cox and Snell, 1968) are available for the Weibull model and the additive log cumulative hazard model. AFT residuals are only available for the Weibull model.

References

Cox, D. and Snell, E. (1968) A general definition of residuals. Journal of the Royal Statistical Society, Series B 30, 248--275.

Rizopoulos, D. (2012) Joint Models for Longitudinal and Time-to-Event Data: with Applications in R. Boca Raton: Chapman and Hall/CRC.

Rizopoulos, D., Verbeke, G. and Molenberghs, G. (2010) Multiple-imputation-based residuals and diagnostic plots for joint models of longitudinal and survival outcomes. Biometrics 66, 20--29.

Rizopoulos, D. (2010) JM: An R Package for the Joint Modelling of Longitudinal and Time-to-Event Data. Journal of Statistical Software 35 (9), 1--33. tools:::Rd_expr_doi("10.18637/jss.v035.i09")

See Also

fitted.jointModel

Examples

if (FALSE) {
# linear mixed model fit
fitLME <- lme(sqrt(CD4) ~ obstime * drug - drug, 
    random = ~ 1 | patient, data = aids)
# cox model fit
fitCOX <- coxph(Surv(Time, death) ~ drug, data = aids.id, x = TRUE)

# joint model fit, under the additive log cumulative hazard model
fitJOINT <- jointModel(fitLME, fitCOX, 
    timeVar = "obstime")

# residuals for the longitudinal outcome
head(cbind(
    "Marginal" = residuals(fitJOINT),
    "std-Marginal" = residuals(fitJOINT, type = "stand-Marginal"),
    "Subject" = residuals(fitJOINT, type = "Subject"),
    "std-Subject" = residuals(fitJOINT, type = "stand-Subject")
))

# residuals for the survival outcome
head(cbind(
    "Martingale" = residuals(fitJOINT, process = "Event", type = "Martingale"),
    "CoxSnell" = residuals(fitJOINT, process = "Event", type = "CoxSnell")
))
}