predict: Predictions from Joint Models

In drizopoulos/JMbayes2: Extended Joint Models for Longitudinal and Time-to-Event Data

Predictions from Joint Models

Description

Predict method for object of class "jm".

Usage

## S3 method for class 'jm'
predict(object, newdata = NULL, newdata2 = NULL, times = NULL,
  all_times = FALSE, times_per_id = FALSE,
  process = c("longitudinal", "event"),
  type_pred = c("response", "link"),
  type = c("subject_specific", "mean_subject"),
  level = 0.95, return_newdata = FALSE, use_Y = TRUE, return_mcmc = FALSE,
  n_samples = 200L, n_mcmc = 55L, parallel = c("snow", "multicore"),
  cores = NULL, seed = 123L,
  ...)

## S3 method for class 'predict_jm'
plot(x, x2 = NULL, subject = 1, outcomes = 1,
  fun_long = NULL, fun_event = NULL, CI_long = TRUE, CI_event = TRUE,
  xlab = "Follow-up Time", ylab_long = NULL, ylab_event = "Cumulative Risk",
  main = "", lwd_long = 2, lwd_event = 2, ylim_long_outcome_range = TRUE,
  col_line_long = "#0000FF",
  col_line_event = c("#FF0000", "#03BF3D", "#8000FF"), pch_points = 16,
  col_points = "blue", cex_points = 1, fill_CI_long = "#0000FF4D",
  fill_CI_event = c("#FF00004D", "#03BF3D4D", "#8000FF4D"), cex_xlab = 1,
  cex_ylab_long = 1, cex_ylab_event = 1, cex_main = 1, cex_axis = 1,
  col_axis = "black", pos_ylab_long = c(0.1, 2, 0.08), bg = "white",
  ...)

## S3 method for class 'jmList'
predict(object, weights, newdata = NULL, newdata2 = NULL,
 times = NULL, all_times = FALSE, times_per_id = FALSE,
 process = c("longitudinal", "event"),
 type_pred = c("response", "link"),
 type = c("subject_specific", "mean_subject"),
 level = 0.95, return_newdata = FALSE,
 return_mcmc = FALSE, n_samples = 200L, n_mcmc = 55L,
 parallel = c("snow", "multicore"),
 cores = parallelly::availableCores(omit = 1L), ...)

Arguments

object	an object inheriting from class "jm" or a list of "jm" objects.
weights	a numeric vector of model weights.
newdata, newdata2	data.frames.
times	a numeric vector of future times to calculate predictions.
all_times	logical; if TRUE predictions for the longitudinal outcomes are calculated for all the times given in the times argumet, not only the ones after the last longitudinal measurement.

.

times_per_id	logical; if TRUE the times argument is a vector of times equal to the number of subjects in newdata.
process	for which process to calculation predictions, for the longitudinal outcomes or the event times.
type_pred	type of predictions; options are "response" using the inverse link function in GLMMs, and "link" that correspond to the linear predictor.
type	level of predictions; only relevant when type_pred = "longitudinal". Option type = "subject_specific" combines the fixed- and random-effects parts, whereas type = "mean_subject" uses only the fixed effects.
level	the level of the credible interval.
return_newdata	logical; should predict() return the predictions as extra columns in newdata and newdata2.
use_Y	logical; should the longitudinal measurements be used in the posterior of the random effects.
return_mcmc	logical; if TRUE the mcmc sample for the predictions is returned. It can be TRUE only in conjuction with return_newdata being FALSE.
n_samples	the number of samples to use from the original MCMC sample of object.
n_mcmc	the number of Metropolis-Hastings iterations for sampling the random effects per iteration of n_samples; only the last iteration is retained.
parallel	character string; what type of parallel computing to use.
cores	how many number of cores to use. If there more than 20 subjects in newdata, parallel computing is invoked with four cores by default. If cores = 1, no parallel computing is used.
seed	an integer denoting the seed.
x, x2	objects returned by predict.jm() with argument return_data set to TRUE.
subject	when multiple subjects are included in the data.frames x and x2, it selects which one to plot. Only a single subject can be plotted each time.
outcomes	when multiple longitudinal outcomes are included in the data.frames x and x2, it selects which ones to plot. A maximum of three outcomes can be plotted each time.
fun_long, fun_event	function to apply to the predictions for the longitudinal and event outcomes, respectively. When multiple longitudinal outcomes are plotted, fun_long can be a list of functions; see examples below.
CI_long, CI_event	logical; should credible interval areas be plotted.
xlab, ylab_long, ylab_event	characture strings or a chracter vector for ylab_long when multiple longitudinal outcomes are considered with the labels for the horizontal axis, and the two vertical axes.
lwd_long, lwd_event, col_line_long, col_line_event, main, fill_CI_long, fill_CI_event, cex_xlab, cex_ylab_long, cex_ylab_event, cex_main, cex_axis, pch_points, col_points, cex_points, col_axis, bg	graphical parameters; see par.
pos_ylab_long	controls the position of the y-axis labels when multiple longitudinal outcomes are plotted.
ylim_long_outcome_range	logical; if TRUE, the range of the y-axis spans across the range of the outcome in the data used to fit the model; not only the range of values of the specific subject being plotted.
...	extra aguments; currently none is used.

Details

A detailed description of the methodology behind these predictions is given here: https://drizopoulos.github.io/JMbayes2/articles/Dynamic_Predictions.html.

Value

Method predict() returns a list or a data.frame (if return_newdata was set to TRUE) with the predictions.

Method plot() produces figures of the predictions from a single subject.

Author(s)

Dimitris Rizopoulos [e-mail]

See Also

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

# we select the subject for whom we want to calculate predictions
# we use measurements up to follow-up year 3; we also set that the patients
# were alive up to this time point
t0 <- 3
ND <- pbc2[pbc2$id %in% c(2, 25), ]
ND <- ND[ND$year < t0, ]
ND$status2 <- 0
ND$years <- t0

# predictions for the longitudinal outcomes using newdata
predLong1 <- predict(jointFit, newdata = ND, return_newdata = TRUE)

# predictions for the longitudinal outcomes at future time points
# from year 3 to 10
predLong2 <- predict(jointFit, newdata = ND,
                     times = seq(t0, 10, length.out = 51),
                     return_newdata = TRUE)

# predictions for the event outcome at future time points
# from year 3 to 10
predSurv <- predict(jointFit, newdata = ND, process = "event",
                    times = seq(t0, 10, length.out = 51),
                    return_newdata = TRUE)

plot(predLong1)
# for subject 25, outcomes in reverse order
plot(predLong2, outcomes = 3:1, subject = 25)

# prediction for the event outcome
plot(predSurv)

# combined into one plot, the first longitudinal outcome and cumulative risk
plot(predLong2, predSurv, outcomes = 1)

# the first two longitudinal outcomes
plot(predLong1, predSurv, outcomes = 1:2)

# all three longitudinal outcomes, we display survival probabilities instead
# of cumulative risk, and we transform serum bilirubin to the original scale
plot(predLong2, predSurv, outcomes = 1:3, fun_event = function (x) 1 - x,
     fun_long = list(exp, identity, identity),
     ylab_event = "Survival Probabilities",
     ylab_long = c("Serum Bilirubin", "Prothrombin", "Ascites"),
     pos_ylab_long = c(1.9, 1.9, 0.08))

drizopoulos/JMbayes2 documentation built on April 20, 2024, 8:52 a.m.