timeplot: Diagnostic plots for the fitted joint model

Description

Creates diagnostic plots for a fitted jmcs object. The function always produces a longitudinal biomarker trajectory plot and an event curve. Optionally, it can also produce a log residual variance plot.

a longitudinal biomarker trajectory plot, and
a plot of log residual variance over follow-up time (optional).

It also produces one event plot based on object$CompetingRisk:

if object$CompetingRisk = FALSE, a Kaplan-Meier plot is shown;
if object$CompetingRisk = TRUE, a cumulative incidence plot is shown.

The event time and status variables are inferred from object$SurvivalSubmodel when event_time_col and event_status_col are not supplied.

Usage

timeplot(
  object,
  biomarker,
  id_col,
  time_col,
  visit_col = NULL,
  n.obs = 100,
  seed = 100,
  window_days = 50,
  time_bin_width = 180,
  show_logvar = FALSE,
  biomarker_y_lab = NULL,
  logvar_y_lab = "Log Residual Variance",
  event_x_lab = NULL,
  event_y_lab = NULL,
  x_lab = NULL,
  x_break_by = NULL,
  ylim_mean = NULL,
  ylim_logvar = NULL,
  event_time_col = NULL,
  event_status_col = NULL,
  fail_code = NULL,
  cr_code = NULL,
  censor_code = 0,
  primary_event_label = "Primary event",
  competing_event_label = NULL,
  km_title = NULL,
  cif_title = NULL,
  center_event_plot = TRUE
)

Value

Invisibly returns a list with components:

combined: The combined plot object.
p1: The biomarker trajectory plot.
p2: The log residual variance plot.
p_cif: The cumulative incidence plot if object$CompetingRisk = TRUE; otherwise NULL.
p_km: The Kaplan-Meier plot if object$CompetingRisk = FALSE; otherwise NULL.
cif_fit: The fitted cumulative incidence object if applicable; otherwise NULL.
km_fit: The fitted Kaplan-Meier object if applicable; otherwise NULL.
event_time_col: The event-time column used.
event_status_col: The event-status column used.
fail_code: The primary event code used.
cr_code: The competing event code used, or NULL for single-failure models.
censor_code: The censoring code used.
summary_data: A data frame of visit- or bin-level longitudinal summary statistics.
obs_per_subject_visit: A data frame giving the number of observations per subject and visit/bin after window-based filtering.
grouping_used: A character string indicating whether summaries were based on an observed visit variable or derived time bins.
show_logvar: a logic value to indicate whether a log residual variance plot is presented.

Arguments

object: A fitted object of class jmcs.
biomarker: Unquoted name of the longitudinal biomarker variable in object$ydata.
id_col: Unquoted name of the subject identifier variable in object$ydata.
time_col: Unquoted name of the longitudinal follow-up time variable in object$ydata. This variable is used on the x-axis for the biomarker trajectory and log residual variance plots.
visit_col: Optional unquoted name of a visit variable in object$ydata. If supplied and found, visit-level summaries are used for the longitudinal diagnostic plots. If omitted, or if the supplied column is not found, derived time bins are used instead.
n.obs: Numeric value specifying the number of subjects randomly selected for the longitudinal biomarker trajectory plot. Default is 100.
seed: Optional integer random seed used for reproducible subject sampling in the longitudinal biomarker trajectory plot. Default is 100. If NULL, no seed is set.
window_days: Numeric value giving the half-width of the time window used when selecting observations around each visit- or bin-level mean time. Default is 50.
time_bin_width: Numeric value giving the width of derived time bins when visit_col is not supplied or not found. Default is 180. For small-scale time variables, such as time ranging from 0 to 5, use a smaller value such as 0.5 or 1.
show_logvar: Logical; if TRUE, produces an additional plot of log residual variance over follow-up time. Default is FALSE.
biomarker_y_lab: Optional character string for the y-axis label of the biomarker trajectory plot. If NULL, the name of biomarker is used.
logvar_y_lab: Character string for the y-axis label of the log residual variance plot. Default is "Log Residual Variance".
event_x_lab: Optional character string for the x-axis label of the event plot. If NULL, the name of the event-time variable is used.
event_y_lab: Optional character string for the y-axis label of the event plot. If NULL, the default label from the Kaplan-Meier or cumulative incidence plotting function is used.
x_lab: Optional character string for the x-axis label of the longitudinal plots. If NULL, the name of time_col is used.
x_break_by: Numeric value controlling spacing of x-axis tick marks in the longitudinal plots. Default is NULL.
ylim_mean: Optional numeric vector of length 2 giving y-axis limits for the biomarker trajectory plot.
ylim_logvar: Optional numeric vector of length 2 giving y-axis limits for the log residual variance plot.
event_time_col: Optional character string giving the event-time variable in object$cdata. If NULL, the function attempts to infer it as the first variable in object$SurvivalSubmodel, i.e. the first argument of Surv(time, status).
event_status_col: Optional character string giving the event-status variable in object$cdata. If NULL, the function attempts to infer it as the second variable in object$SurvivalSubmodel, i.e. the second argument of Surv(time, status).
fail_code: Numeric or integer code in event_status_col denoting the event of interest. For single-failure models, this is the event code used for the Kaplan-Meier plot. For competing-risk models, this is the primary event code used in the cumulative incidence plot. If the model is single-failure and there is exactly one non-censoring status code, fail_code can be inferred.
cr_code: Numeric or integer code in event_status_col denoting the competing event. Required for competing-risk models unless there is exactly one other non-censoring status code besides fail_code, in which case it can be inferred. Ignored for single-failure Kaplan-Meier plots.
censor_code: Numeric or integer code in event_status_col denoting censoring. Default is 0.
primary_event_label: Character string used in event plot labels for the primary event. Default is "Primary event".
competing_event_label: Character string used in cumulative incidence plot labels for the competing event. Required for informative competing-risk labeling. Ignored for single-failure Kaplan-Meier plots. Default is NULL.
km_title: Optional character string for the Kaplan-Meier plot title. If NULL, a default title is constructed from primary_event_label.
cif_title: Optional character string for the cumulative incidence plot title. If NULL, a default title is constructed from primary_event_label and competing_event_label.
center_event_plot: Logical; if TRUE, the three-plot layout places the two longitudinal diagnostic plots on the first row and centers the event plot on the second row. If FALSE, the three plots are stacked in one column. Default is TRUE.

Author

Shanpeng Li lishanpeng0913@ucla.edu

Details

The longitudinal trajectory plot displays individual biomarker trajectories for a random subset of subjects, along with a summary mean curve. If visit_col is supplied and found in object$ydata, summaries are calculated by observed visit. Otherwise, the function creates derived time bins using floor(time_col / time_bin_width).

The residual variance plot displays the log residual variance over visit- or bin-level follow-up time. Subject-level fitted values are obtained using fitted(object, type = "Subject", process = "Longitudinal").

The event plot is chosen automatically from the fitted model:

For CompetingRisk = FALSE, the function creates a Kaplan-Meier plot using fail_code as the event code and censor_code as the censoring code.
For CompetingRisk = TRUE, the function creates a cumulative incidence plot using fail_code as the primary event and cr_code as the competing event.

In competing-risk settings, the model identifies event codes, but it does not determine which event is scientifically "primary." The user should choose fail_code based on the scientific question. For example, if status = 1 is heart failure and status = 2 is death, then fail_code = 1 and cr_code = 2 answer the question: "What is the cumulative incidence of heart failure over time, accounting for death before heart failure?"

Examples

Run this code

# \donttest{
library(FastJM)

data(ydata)
data(cdata)

# Single-failure example:
# Treat failure_type == 1 as the only event and all other observations as censored.
cdata_single <- cdata
cdata_single$event_single <- as.integer(cdata_single$failure_type == 1)

fit_single <- jmcs(
  ydata = ydata,
  cdata = cdata_single,
  long.formula = response ~ time + gender + x1 + race,
  surv.formula = Surv(surv, event_single) ~ x1 + gender + x2 + race,
  random = ~ time | ID
)

singleplot <- timeplot(
  object = fit_single,
  biomarker = response,
  id_col = ID,
  time_col = time,
  time_bin_width = 0.5,
  primary_event_label = "Event type 1"
)

singleplot$combined
singleplot$p_km

# Competing-risk example using FastJM simulated data.
fit_cr <- jmcs(
  ydata = ydata,
  cdata = cdata,
  long.formula = response ~ time + gender + x1 + race,
  surv.formula = Surv(surv, failure_type) ~ x1 + gender + x2 + race,
  random = ~ time | ID
)

crplot <- timeplot(
  object = fit_cr,
  biomarker = response,
  id_col = ID,
  time_col = time,
  time_bin_width = 0.5,
  fail_code = 1,
  cr_code = 2,
  censor_code = 0,
  primary_event_label = "Event type 1",
  competing_event_label = "Event type 2"
)

crplot$combined
crplot$p_cif

# }

Run the code above in your browser using DataLab