Turn exact event times into interval-censored observations

Source: R/sim-ic.R

Convenience helper to manufacture interval-censored (panel) data from exact simulated survival times (e.g.\ the output of sim_pexp), for coverage studies and examples. Each subject is "inspected" at a sequence of times; the true event time is then only known to lie between the last clean and the first positive inspection. The exact time is retained (by default in column true_time) so that coverage can be scored against the truth.

add_inspections(
  data,
  time_var = "time",
  status_var = "status",
  mechanism = c("random", "fixed", "mixed"),
  rate = 1,
  schedule = NULL,
  max_time = NULL,
  terminal_exam = TRUE,
  keep_truth = TRUE,
  L = "L",
  R = "R"
)

Arguments

data

A data frame with one row per subject containing an exact event time and a status indicator (as produced by sim_pexp).

time_var, status_var

Names of the (exact) event-time and status columns. status_var may be missing, in which case all rows are treated as events.

mechanism

Inspection mechanism: "random" (default) draws inter-inspection gaps from an Exp(rate) distribution; "fixed" uses the common grid given in schedule; "mixed" jitters the fixed grid by a random offset per subject.

rate

Inspection rate for mechanism = "random" / "mixed" (expected gap \(1/\mathrm{rate}\)).

schedule

Numeric vector of inspection times for mechanism = "fixed"/"mixed".

max_time

Inspection horizon. Defaults to max(data[[time_var]]).

terminal_exam

Logical; if TRUE (default), every subject is additionally examined at max_time (an end-of-study examination), so events before max_time always have a finite upper bound and only subjects event-free at max_time are right-censored. If FALSE, there is no closing examination: events after a subject's last inspection are right-censored at that inspection, and subjects that exit event-free (status == 0) are likewise right-censored at their last inspection before exit (not at their exact exit time). Both conventions yield coarsening-at-random data; mixing them (exact exit times for survivors but open intervals for undetected events) would make the right-censoring informative and bias every interval-censoring likelihood.

keep_truth

Logical; keep the exact event time in true_time.

L, R

Names of the created lower/upper bound columns.

Value

data augmented with interval bounds in columns L and R (and true_time). Use Surv(L, R, type = "interval2") on the result.

See also

pamm_ic, sim_pexp

Examples

if (FALSE) { # \dontrun{
set.seed(1)
df <- data.frame(x = runif(100, -1, 1))
sdf <- sim_pexp(~ -2 + 0.4 * x, df, cut = seq(0, 10, by = 0.5))
icd <- add_inspections(sdf, rate = 1)
fit <- pamm_ic(Surv(L, R, type = "interval2") ~ x, icd, m = 5)
} # }