Using the available longitudinal information up to a starting time point, these functions compute estimates of the ROC curve and the AUC, the Brier score and expected predictive cross-entropy at a horizon time point based on joint models.

tvROC(object, newdata, Tstart, ...)

# S3 method for jm
tvROC(object, newdata, Tstart, Thoriz = NULL,
    Dt = NULL, ...)

tvAUC(object, newdata, Tstart, ...)

# S3 method for jm
tvAUC(object, newdata, Tstart, Thoriz = NULL,
    Dt = NULL, ...)

# S3 method for tvROC
tvAUC(object, ...)

calibration_plot(object, newdata, Tstart, Thoriz = NULL,
    Dt = NULL, df_ns = 3, plot = TRUE, add_density = TRUE,
    col = "red", lty = 1, lwd = 1,
    col_dens = "grey", xlab = "Predicted Probabilities",
    ylab = "Observed Probabilities", main = "", ...)

calibration_metrics(object, newdata, Tstart, Thoriz = NULL,
    Dt = NULL, df_ns = 3, ...)

tvBrier(object, newdata, Tstart, Thoriz = NULL, Dt = NULL,
    integrated = FALSE, type_weights = c("model-based", "IPCW"),
    model_weights = NULL, eventData_fun = NULL,
    parallel = c("snow", "multicore"),
    cores = parallelly::availableCores(omit = 1L), ...)

tvEPCE(object, newdata, Tstart, Thoriz = NULL, Dt = NULL, eps = 0.001,
    model_weights = NULL, eventData_fun = NULL,
    parallel = c("snow", "multicore"),
    cores = parallelly::availableCores(omit = 1L), ...)

create_folds(data, V = 5, id_var = "id", strata = NULL, seed = 123L)

Arguments

object

an object inheriting from class jm, except for tvAUC.tvROC() where this is an object of class tvROC. For tvBrier() and tvEPCE() it can also be a library of joint models.

newdata

a data.frame that contains the longitudinal and covariate information for the subjects for which prediction of survival probabilities is required. The names of the variables in this data.frame must be the same as in the data.frames that were used to fit the linear mixed effects and the event process model that were supplied as the two first argument of jm.

Tstart

numeric scalar denoting the time point up to which longitudinal information is to be used to derive predictions.

Thoriz

numeric scalar denoting the time point for which a prediction of the survival status is of interest; Thoriz must be later than Tstart and either Dt or Thoriz must be specified. If Thoriz is NULL is set equal to Tstart + Dt.

Dt

numeric scalar denoting the length of the time interval of prediction; either Dt or Thoriz must be specified.

integrated

logical; if TRUE the integrated Brier score is calculated.

type_weights

character string denoting the type of weights to use to account for censorting. Options are model-based (default) and inverse probability of censoring weighting (using the Kaplan-Meier estimate of the censoring distribution).

eps

numeric scalar used in the approximation of the hazard function.

model_weights

a numeric vector of weights to combine predictions when object is a list of joint models of class "jmList".

eventData_fun

a function that takes as input the newdata and produces the dataset used for the event process model. This is useful when, for example, the event process model contains other time-varying covariates. It is important that this function does not alter the ordering of the subjects in newdata.

parallel

character string; what type of parallel computing to use.

cores

integer denoting the number of cores to be used when a library of joint models has been provided in object. If cores = 1, no parallel computing is used.

df_ns

the degrees of freedom for the natural cubic spline of the cloglog transformation of the predicted probabilities used in the Cox model that assess calibration.

plot

logical; should a plot be produced. If FALSE, a list is returned with the observed and predicted probabilities.

add_density

logical; should the kernal density estimation of the predicted probabilities be superimposed in the calibration plot.

col, lwd, lty, col_dens, xlab, ylab, main

graphical parameters.

data

the data.frame to split in folds.

V

numeric scalar denoting the number of folds.

id_var

character string denoting the name of the subject id variable in data.

strata

character vector with the names of stratifying variables.

seed

integer denoting the seed.

...

additional arguments passed to predict.jm().

Value

A list of class tvAUC with components:

auc

a numeric scalar denoting the estimated prediction error.

Tstart

a copy of the Tstart argument.

Thoriz

a copy of the Thoriz argument.

nr

a numeric scalar denoting the number of subjects at risk at time Tstart.

classObject

the class of object.

nameObject

the name of object.

A list of class tvROC with components:

TP, FP, nTP, nFN, nTN, qSN, qSP, qOverall

accuracy indexes.

F1score, Youden

numeric scalars with the optimal cut-point using the F1 score and the Youden index.

thr

numeric vector of thresholds.

Tstart

a copy of the Tstart argument.

Thoriz

a copy of the Thoriz argument.

nr

a numeric scalar denoting the number of subjects at risk at time Tstart.

classObject

the class of object.

nameObject

the name of object.

References

Antolini, L., Boracchi, P., and Biganzoli, E. (2005). A time-dependent discrimination index for survival data. Statistics in Medicine 24, 3927--3944.

Commenges, D., Liquet, B., and Proust-Lima, C. (2012). Choice of prognostic estimators in joint models by estimating differences of expected conditional Kullback-Leibler risks. Biometrics 68, 380--387.

Harrell, F., Kerry, L. and Mark, D. (1996). Multivariable prognostic models: issues in developing models, evaluating assumptions and adequacy, and measuring and reducing errors. Statistics in Medicine 15, 361--387.

Heagerty, P. and Zheng, Y. (2005). Survival model predictive accuracy and ROC curves. Biometrics 61, 92--105.

Rizopoulos, D. (2016). The R package JMbayes for fitting joint models for longitudinal and time-to-event data using MCMC. Journal of Statistical Software 72(7), 1--45. doi:10.18637/jss.v072.i07.

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

Rizopoulos, D. (2011). Dynamic predictions and prospective accuracy in joint models for longitudinal and time-to-event data. Biometrics 67, 819--829.

Rizopoulos, D., Molenberghs, G. and Lesaffre, E.M.E.H. (2017). Dynamic predictions with time-dependent covariates in survival analysis using joint modeling and landmarking. Biometrical Journal 59, 1261--1276.

Author

Dimitris Rizopoulos d.rizopoulos@erasmusmc.nl

See also

Examples

# \donttest{
# We fit a multivariate joint model
pbc2.id$status2 <- as.numeric(pbc2.id$status != 'alive')
CoxFit <- coxph(Surv(years, status2) ~ sex, data = pbc2.id)
fm1 <- lme(log(serBilir) ~ ns(year, 3) * sex, data = pbc2,
           random = ~ ns(year, 3) | id, control = lmeControl(opt = 'optim'))
fm2 <- lme(prothrombin ~ ns(year, 2) * sex, data = pbc2,
           random = ~ ns(year, 2) | id, control = lmeControl(opt = 'optim'))
fm3 <- mixed_model(ascites ~ year * sex, data = pbc2,
                   random = ~ year | id, family = binomial())

jointFit <- jm(CoxFit, list(fm1, fm2, fm3), time_var = "year", n_chains = 1L)

roc <- tvROC(jointFit, newdata = pbc2, Tstart = 4, Dt = 3, cores = 1L)
roc
#> 
#> 	Time-dependent Sensitivity and Specificity for the Joint Model jointFit
#> 
#> At time: 7
#> Using information up to time: 4 (225 subjects still at risk)
#> 
#>    cut-off         SN        SP        qSN        qSP  
#> 1     0.03 0.02586716 0.9954094 0.01713054 0.48356191  
#> 2     0.07 0.08310400 0.9931910 0.06226546 0.69359507  
#> 3     0.11 0.10510387 0.9876214 0.07636868 0.60211556  
#> 4     0.12 0.12710374 0.9876214 0.09492323 0.65185111  
#> 5     0.16 0.17110348 0.9876214 0.13255015 0.72148089  
#> 6     0.17 0.18262181 0.9849678 0.14060704 0.69252315  
#> 7     0.18 0.18262181 0.9793982 0.13657233 0.61371568  
#> 8     0.19 0.21835366 0.9773050 0.16649087 0.63525924  
#> 9     0.20 0.21835366 0.9717354 0.16252178 0.57603086  
#> 10    0.22 0.25543416 0.9699837 0.19458022 0.60272504  
#> 11    0.23 0.26949294 0.9679733 0.20597058 0.59966565  
#> 12    0.24 0.28402784 0.9660834 0.21799157 0.59835574  
#> 13    0.26 0.30602771 0.9605137 0.23458938 0.57693298  
#> 14    0.27 0.32802758 0.9605137 0.25520298 0.59616330  
#> 15    0.28 0.34409073 0.9534411 0.26577321 0.56351069  
#> 16    0.30 0.36609060 0.9534411 0.28685193 0.58097026  
#> 17    0.32 0.38809047 0.9534411 0.30814249 0.59708679  
#> 18    0.33 0.41009034 0.9534411 0.32964812 0.61200950  
#> 19    0.37 0.41009034 0.9478715 0.32624531 0.58111036  
#> 20    0.38 0.43209021 0.9423019 0.34471947 0.56726412  
#> 21    0.40 0.45409008 0.9423019 0.36685705 0.58122334  
#> 22    0.42 0.46456365 0.9338142 0.37253553 0.54873306  
#> 23    0.47 0.48656352 0.9338142 0.39516645 0.56200561  
#> 24    0.49 0.50856339 0.9282446 0.41495641 0.55152846  
#> 25    0.50 0.50856339 0.9226749 0.41184448 0.52977995  
#> 26    0.51 0.51310163 0.9182542 0.41415972 0.51597897  
#> 27    0.52 0.52020267 0.9144823 0.41960000 0.50662890  
#> 28    0.53 0.54220254 0.9089127 0.44019332 0.50013075  
#> 29    0.54 0.56420241 0.9089127 0.46418329 0.51203239  
#> 30    0.55 0.57248096 0.9054389 0.47147371 0.50520374  
#> 31    0.56 0.61648070 0.8998693 0.51792266 0.51023031  
#> 32    0.57 0.63848057 0.8942997 0.54044140 0.50452975  
#> 33    0.58 0.64704408 0.8908980 0.54877794 0.49902164  
#> 34    0.59 0.66904395 0.8908980 0.57448508 0.50904120  
#> 35    0.60 0.66904395 0.8853284 0.57203959 0.49409596  
#> 36    0.63 0.67206337 0.8805232 0.57349283 0.48303310  
#> 37    0.64 0.69406324 0.8749536 0.59745164 0.47897323 *
#> 38    0.65 0.69406324 0.8638143 0.59268775 0.45282539  
#> 39    0.67 0.69406324 0.8526751 0.58780976 0.42848084  
#> 40    0.68 0.70422212 0.8441077 0.59666653 0.41540385  
#> 41    0.69 0.70422212 0.8385381 0.59420718 0.40444368  
#> 42    0.71 0.70422212 0.8329684 0.59171766 0.39383706  
#> 43    0.72 0.73035366 0.8173055 0.61842499 0.37717800  
#> 44    0.73 0.75346842 0.8064485 0.64442560 0.36885394  
#> 45    0.75 0.75346842 0.7953093 0.63980775 0.35133224  
#> 46    0.76 0.75346842 0.7897397 0.63745355 0.34293643  
#> 47    0.77 0.75346842 0.7841700 0.63506838 0.33477064  
#> 48    0.78 0.77546829 0.7674611 0.65865111 0.32050334  
#> 49    0.79 0.77546829 0.7507523 0.65158872 0.29899072  
#> 50    0.80 0.77546829 0.7396130 0.64671584 0.28552347  
#> 51    0.81 0.77764697 0.7345949 0.64768006 0.28052845  
#> 52    0.82 0.78340546 0.7249135 0.65190163 0.27182996  
#> 53    0.83 0.80809490 0.7144552 0.68482740 0.26991384  
#> 54    0.84 0.81329734 0.6934938 0.68414964 0.25039235  
#> 55    0.85 0.83529721 0.6823545 0.71493749 0.24768172  
#> 56    0.86 0.84386161 0.6455353 0.71438100 0.21809262  
#> 57    0.87 0.86586148 0.6455353 0.75261339 0.22568396  
#> 58    0.88 0.87272479 0.6082855 0.75098329 0.19876576  
#> 59    0.89 0.87634263 0.5535051 0.73501993 0.16282208  
#> 60    0.90 0.87844766 0.5094810 0.71804869 0.13775958  
#> 61    0.91 0.88009578 0.4987590 0.71601633 0.13246749  
#> 62    0.92 0.88038568 0.4765539 0.70425030 0.12107926  
#> 63    0.93 0.88402084 0.4273475 0.68176451 0.09897337  
#> 64    0.94 0.92935944 0.3775598 0.77613908 0.09059064  
#> 65    0.95 0.92935944 0.3274332 0.74364314 0.07161019  
#> 66    0.96 0.97505267 0.2554567 0.88057130 0.05886383  
#> 67    0.97 0.99896423 0.1334089 0.99028961 0.02993530  
#> 68    0.98 0.99963102 0.0611725 0.99245261 0.01291501  
#> 
tvAUC(roc)
#> 
#> 	Time-dependent AUC for the Joint Model jointFit
#> 
#> Estimated AUC: 0.8343
#> At time: 7
#> Using information up to time: 4 (225 subjects still at risk)
#> 
plot(roc, legend = TRUE, optimal_cutoff = "Youden")

# }