Compute Total Time in Target State(s)

Calculates the expected total time spent in specified target state(s). By default this sums state occupancy probabilities over visit-scale unit steps. When time_map is supplied, it maps/interpolates to real time and uses trapezoidal AUC. Already interpolated SOP output from interpolate_sops() is integrated on its current real-time grid. It automatically adapts to the input format:

Patient-Level: If input is an array from soprob_markov, it returns time-in-state for each patient.
Tidy SOP: If input is a markov_sops or markov_avg_sops object, it returns grouped total time. Stored simulation, bootstrap, or posterior draws are reduced identically and used to recompute confidence intervals and standard errors.
Legacy Wide Bootstrap-Level: If input is a data frame with boot_id, time, tx, and state_* columns, it returns mean time-in-state per treatment group and the difference for each bootstrap sample.

Usage

time_in_state(
  x,
  target_states = 1,
  time_map = NULL,
  baseline_time = 0,
  target_times = NULL
)

Arguments

x

Input object.

Array: [Patients x Time x States] (Frequentist) or [Draws x Patients x Time x States] (Bayes).
Tidy SOP: A markov_sops, markov_avg_sops, or markov_interpolated_sops object.
Data Frame: Legacy wide bootstrap SOP data containing columns boot_id, time, tx, and state_*.

target_states

Vector of target state(s) to include in the time calculation. Can be integer indices or character names (e.g., 1 or c("Home", "Rehab")). For bootstrap outputs, these must match the suffix of the state_ columns (e.g., if column is state_1, use 1).

time_map

Optional named numeric vector or data frame mapping visit labels to real elapsed times. Supplying this switches tidy SOP and array inputs to trapezoidal real-time AUC.

baseline_time

Real time of the observed baseline state for tidy SOP outputs. The default 0 supplies a fixed interpolation anchor to interpolate_sops(). Set to NULL to disable baseline anchoring.

target_times

Optional numeric real-time grid for tidy SOP outputs when time_map is supplied. This controls the interpolation grid used for AUC, for example target_times = 1:28 with baseline_time = 0 uses day 0 as an anchor but starts the AUC at day 1. If NULL, integration runs from baseline_time through the mapped follow-up times, matching avg_time() and avg_comparisons(). With baseline_time = NULL, it starts at the first mapped follow-up time.

Value

Input = Array (Frequentist): A named numeric vector of length n_patients.
Input = Array (Bayesian): A matrix of dimension [n_draws x n_patients].
Input = Tidy SOP: A data frame with total_time and grouping columns. When stored draws are available, draw-based conf.low, conf.high, and std.error columns are recomputed and the reduced draws are retained in a draws attribute. Any draw-specific baseline anchors have already been propagated by interpolate_sops().
Input = Bootstrap DF: A tibble with columns:
- boot_id: Bootstrap iteration
- SOP_tx: Mean time in target state (Treatment)
- SOP_ctrl: Mean time in target state (Control)
- delta: Difference (Treatment - Control)

Examples

if (FALSE) { # \dontrun{
# --- Scenario 1: Patient-Level Estimates ---
sops_arr <- soprob_markov(model, data, times = 1:30, y_levels = 1:6)
days_home <- time_in_state(sops_arr, target_states = 1)

# Real-time AUC after fitting on factor visit indices
real_days_home <- time_in_state(
  avg,
  target_states = 1,
  time_map = c("1" = 3, "2" = 7, "3" = 14, "4" = 28),
  baseline_time = 0,
  target_times = 1:28
)

# --- Scenario 2: Bootstrap Inference ---
avg_boot <- avg_sops(
  model,
  variables = list(tx = c(0, 1)),
  times = 1:30,
  y_levels = 1:6,
  id_var = "id"
) |>
  inferences(method = "bootstrap", n_draws = 100)
boot_effects <- time_in_state(avg_boot, target_states = 1)
} # }

Usage

Arguments

Value

See also

Examples