calibration_plot: Calibration Plot for Dynamic Predictions under Right-Censored...

calibration_plotR Documentation

Calibration Plot for Dynamic Predictions under Right-Censored Data

Description

Displays a calibration plot at a specified horizon time (Thoriz), using longitudinal information available up to a given starting time point (Tstart). The function supports both joint models and Cox proportional hazards models. The calibration_metrics() function calculates metrics for the accuracy of predictions: The ICI is the mean absolute difference between the observed and predicted probabilities, E50 is the median absolute difference, and E90 is the 90% percentile of the absolute differences.

Usage

calibration_plot(object, newdata, Tstart, ...)

## S3 method for class 'jm'
calibration_plot(object, newdata, Tstart, Thoriz = NULL,
    Dt = NULL, df_ns = NULL, plot = TRUE,
    col = "red", lty = 1, lwd = 1,
    add_CI = TRUE, col_CI = "lightgrey",
    add_density = TRUE, col_dens = "grey",
    xlab = "Predicted Probabilities",
    ylab = "Observed Probabilities", main = "", ...)

## S3 method for class 'coxph'
calibration_plot(object, newdata, Tstart, Thoriz = NULL,
    Dt = NULL, df_ns = NULL, plot = TRUE,
    col = "red", lty = 1, lwd = 1,
    add_CI = TRUE, col_CI = "lightgrey",
    add_density = TRUE, col_dens = "grey",
    xlab = "Predicted Probabilities",
    ylab = "Observed Probabilities", main = "", ...)

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

Arguments

object

an object inheriting from class jm or coxph.

newdata

a data.frame that contains the longitudinal and covariate information for the subjects for which prediction of survival probabilities is required. If a jm object is used, 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. If a coxph is used it only applies to the event process.

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.

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 assesses calibration. The default is 3 unless there are less than 25 events in the interval (Tstart, Thoriz] in which case it is 2.

plot

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

add_CI

logical; should 0.95 pointwise confidence intervals be added around the calibration line.

col_CI

character; the color of the shaded area representing the 0.95 pointwise confidence intervals around the calibration line.

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.

...

additional arguments passed to predict.jm().

Value

If plot = TRUE (the default) a calibration plot is returned. Otherwise, a list with the following components is returned:

observed

numeric vector with observed probabilities.

predicted

grid of probabilities used as x-axis in the calibration plot.

pi_u_t

numeric vector with predicted probabilities.

obs_pi_u_t

transformed predicted probabilities using the Cox model with the cloglog transformation.

low

lower bound of the 95% confidence interval for the observed probabilities.

upp

upper bound of the 95% confidence interval for the observed probabilities.

For the calibration_metrics() function, a numeric vector with the following components is returned:

ICI

numeric scalar denoting the mean absolute difference between the observed and predicted probabilities.

E50

numeric scalar denoting the median absolute difference between the observed and predicted probabilities.

E90

numeric scalar denoting the 90% percentile of absolute differences between the observed and predicted probabilities.

Author(s)

Dimitris Rizopoulos d.rizopoulos@erasmusmc.nl

References

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.

See Also

predict, jm

Examples


# 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'))

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

# We use landmark time 4 and prediction horizon 3:
calibration_plot(jointFit, newdata = pbc2, Tstart = 4, Dt = 3, cores = 1L)

# Now the calibration metrics:
calibration_metrics(jointFit, pbc2, Tstart = 4, Thoriz = 7, cores = 1L)


JMbayes2 documentation built on Nov. 19, 2026, 1:07 a.m.