Prepare goodness-of-follow-up data for plotting

Validates dates, builds per-patient follow-up frames, and returns an hv_followup object containing the data for both the death panel (type = "followup") and, optionally, the event panel (type = "event"). Call plot.hv_followup on the result to obtain a bare ggplot2 object.

Usage

hv_followup(
  data,
  iv_opyrs_col = "iv_opyrs",
  death_col = "dead",
  death_time_col = "iv_dead",
  event_col = NULL,
  event_time_col = NULL,
  death_for_event_col = NULL,
  origin_year = 1990,
  study_start = as.Date("1990-01-01"),
  study_end = as.Date("2019-12-31"),
  close_date = as.Date("2021-08-06"),
  tolower_names = TRUE,
  death_levels = c("Alive", "Dead"),
  event_levels = c("No event", "Non-fatal event", "Death"),
  segment_drop = 0
)

Arguments

data: A data frame with one row per patient. See sample_goodness_followup_data.
iv_opyrs_col: Name of the operation-year column. Default "iv_opyrs".
death_col: Name of the binary death-indicator column. Default "dead".
death_time_col: Name of the time-to-death column. Default "iv_dead".
event_col: Name of the non-fatal event indicator column. Required to compute the event panel (type = "event"). Default NULL (event panel unavailable). The flag alone does not decide the state: the event time is compared against death_time_col, and a flagged event is only counted as non-fatal when it strictly precedes death. Ties go to death.
event_time_col: Name of the time-to-event column. Required when event_col is supplied. Default NULL.
death_for_event_col: Name of the death column to use specifically in the event panel (defaults to death_col when NULL).
origin_year: Integer; calendar year used as the y-axis origin. Default 1990.
study_start: Start of study period. Default as.Date("1990-01-01").
study_end: End of study enrollment. Default as.Date("2019-12-31").
close_date: Data close date. Must be $\geq$ study_end. Default as.Date("2021-08-06").
tolower_names: Logical; if TRUE, column names are lower-cased when materialising the data. Default TRUE.
death_levels: Length-2 character vector labeling the two death states (alive first). Default c("Alive", "Dead").
event_levels: Length-3 character vector for the event panel (event-free, non-fatal event, death). Default c("No event", "Non-fatal event", "Death").
segment_drop: Numeric; vertical offset (years) for the segment endpoint below the follow-up point. Default 0 (no segment drawn). Set to a positive value to restore the legacy stem below each point.

Value

An object of class c("hv_followup", "hv_data"):

$data: Per-patient data frame for the death panel.
$meta: Column names, date parameters, state levels, has_event flag, and the cohort counts n_patients (analyzed), n_input, and n_excluded.
$tables: Named list with diagonal (the study-period reference diagonal) and, when event columns are supplied, event_data.

Missing data

Patients with a missing value in any required column are excluded, with a warning naming the columns responsible. $meta$n_patients reports the analyzed cohort, alongside $meta$n_input and $meta$n_excluded, so the reported N always describes the plotted points.

The event panel requires more columns than the death panel, so the two can have different cohorts: a patient with a complete death record but a missing event time appears in one panel and not the other. Each panel is therefore filtered and warned about separately, and the event panel's counts are reported as $meta$n_event_patients and $meta$n_event_excluded.

Examples

dta <- sample_goodness_followup_data()

# 1. Build data object
gf <- hv_followup(dta)
gf  # prints follow-up summary
#> <hv_followup>
#>   N patients  : 300
#>   Study period: 1990-01-01 – 2019-12-31 (close: 2021-08-06)
#>   Death col   : dead / iv_dead
#>   Panels      : followup

# 2. Bare plot -- undecorated ggplot returned by plot.hv_followup
p <- plot(gf)

# 3. Decorate: color palette, axis labels, theme
p +
  ggplot2::scale_color_manual(
    values = c("Alive" = "steelblue", "Dead" = "firebrick"),
    name = NULL
  ) +
  ggplot2::labs(x = "Operation Date", y = "Follow-up (years)") +
  theme_hv_poster()


# With event panel -- same 3-step pattern
gf2 <- hv_followup(dta, event_col = "ev_event", event_time_col = "iv_event")
plot(gf2, type = "event") +
  ggplot2::scale_color_manual(
    values = c("No event" = "blue", "Non-fatal event" = "green3",
               "Death" = "red"),
    name = NULL
  ) +
  ggplot2::scale_shape_manual(values = c(1, 2, 4), name = NULL) +
  ggplot2::labs(x = "Operation Date", y = "Follow-up (years)") +
  theme_hv_poster()