Average Comparisons From Markov State Occupancy Probabilities

Computes average contrasts between counterfactual state occupancy summaries. The first value in variables[[1]] is the reference level, and every later value is compared to it. Reverse the order of values to reverse the contrast.

Usage

avg_comparisons(
  model,
  newdata = NULL,
  variables,
  estimand = c("sop", "time_in_state", "time_benefit"),
  state_sets = NULL,
  comparison = c("difference", "ratio"),
  by = NULL,
  times,
  y_levels = NULL,
  absorb = NULL,
  time_map = NULL,
  baseline_time = 0,
  target_times = NULL,
  time_unit = NULL,
  id_var = NULL,
  time_var = "time",
  p_var = "yprev",
  p2_var = NULL,
  gap_var = NULL,
  time_covariates = NULL,
  include_re = FALSE,
  n_draws = 100L,
  seed = NULL,
  posterior_summary = c("mean", "median"),
  conf_level = 0.95,
  return_draws = FALSE,
  ...
)

Arguments

model

A fitted Markov transition model supported by avg_sops().

newdata

Optional data frame of standardization profiles. See avg_sops().

variables

A named list with one counterfactual variable. The variable must contain at least two values, for example list(tx = c(0, 1)).

estimand

Character scalar. One of "sop", "time_in_state", or "time_benefit".

state_sets

State selection for "sop" and "time_in_state". NULL returns one result per state. An atomic vector is treated as one lumped state set. A named list returns one result per named state set.

comparison

Character scalar. "difference" computes comparison level minus reference level. "ratio" computes comparison level divided by reference level. "time_benefit" only supports "difference".

by

Optional character vector of variables to stratify by after standardization.

times

Required. The consecutive visits to include, in increasing order, for example times = 1:30. Each value is one transition, so leaving out visits does not skip time; see the section "Choosing visits" and avg_sops().

y_levels

A vector of state levels. See avg_sops().

absorb

The absorbing state. See avg_sops().

time_map

Optional named numeric vector or data frame mapping visit labels to real elapsed times. Used by "time_in_state" and "time_benefit".

baseline_time

Real time at which patients are in their starting state, used with time_map. The default 0 means that real-time totals start from the starting state at time 0. Set to NULL to start at the first mapped visit instead. See interpolate_sops().

target_times

Optional numeric grid of real times, used with time_map. Probabilities are linearly interpolated at these times, and totals are calculated with the trapezoidal rule over the grid. When omitted, the grid is baseline_time followed by the mapped visit times, so totals cover the whole period from the starting state to the last visit. With baseline_time = NULL, the omitted grid is the mapped visit times only.

time_unit

Optional label stored in output.

id_var

Name of the patient ID variable. See avg_sops().

time_var

Name of the time variable in the model. See avg_sops().

p_var

Name of the previous state variable in the model. See avg_sops().

p2_var

Optional second previous-state variable. See avg_sops().

gap_var

Optional name of the variable holding the time elapsed since the previous visit, if the model includes one. See avg_sops().

time_covariates

Optional time-varying covariate lookup table for explicit precomputed time-basis columns. See avg_sops().

include_re

Logical. For rmsb::blrm() fits with cluster(), include fitted random-effect draws in posterior predictions for known IDs.

n_draws

Integer number of posterior draws to sample for blrm, or NULL to use all stored draws.

seed

Optional random seed for reproducible posterior draw sampling.

posterior_summary

Summary used for blrm posterior comparison draws: "mean" or "median".

conf_level

Confidence level for blrm posterior intervals.

return_draws

Logical. For blrm, store posterior comparison draws. Frequentist uncertainty draws are stored by inferences().

...

Additional arguments reserved for future extensions.

Value

A data frame of class markov_avg_comparisons.

Details

estimand = "sop" and estimand = "time_in_state" are computed from marginal SOPs. estimand = "time_benefit" is computed before marginalization from paired patient/profile-level counterfactual state distributions, because it is nonlinear in the two state distributions.

Frequentist uncertainty follows the existing package workflow: avg_comparisons(...) |> inferences(...). Bayesian blrm models use their posterior SOP draws directly and therefore return uncertainty from avg_comparisons().

For supported frequentist models, inferences(method = "delta") provides analytical intervals for differences in SOPs or time in state. The default vcov = "unconditional" accounts for coefficient estimation and sampling the patients used in the averages. Use vcov = "conditional" to treat those patients' starting states and covariates as given and account only for coefficient estimation. User-supplied newdata requires the conditional choice. See inferences() for model restrictions.

Choosing visits

SOPs are calculated one visit at a time. The first value of times is the first transition from the starting state, and each later value is one more transition. The values set the time variable, and any time-varying covariates, for each transition; they do not say how much time passes between transitions. Leaving out visits therefore does not skip time. With daily visits, times = c(1, 7, 14) gives the probabilities after 1, 2, and 3 transitions, labelled 1, 7, and 14, instead of the probabilities on days 7 and 14. To get SOPs at selected visits, request every visit, such as times = 1:14, and keep the rows you need.

When newdata is omitted, each patient starts from their state before the first follow-up visit (first_followup_time of the fitting wrapper), so times must begin at that visit. Each row of a supplied newdata starts from its previous state at the first requested visit, which may be a later visit.

A warning is given when times leaves out visits that occur in the data the model was fitted to, is not in increasing order, or, when newdata is omitted, does not begin at the first follow-up visit. Times after the last fitted visit are allowed. There is no warning when gap_var is supplied, because each transition then uses its own elapsed time, so the visits may be spaced unevenly.

See also

avg_sops(), sops(), inferences()

Examples

if (FALSE) { # \dontrun{
avg_comparisons(
  fit,
  variables = list(tx = c(0, 1)),
  estimand = "time_in_state",
  state_sets = "1",
  times = 1:30,
  y_levels = 1:6,
  absorb = 6
) |>
  inferences(method = "mvn", n_draws = 500)
} # }