add_inspections: Turn exact event times into interval-censored observations

In pammtools: Piece-Wise Exponential Additive Mixed Modeling Tools for Survival Analysis

Turn exact event times into interval-censored observations

Description

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.

Usage

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

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)

pammtools documentation built on Aug. 27, 2026, 1:08 a.m.