cmest_multistate is used to implement the multistate approach by Valeri et al. (2023) for causal mediation analysis.

cmest_multistate(
  data = NULL,
  outcome = NULL,
  yevent = NULL,
  mediator = NULL,
  mevent = NULL,
  exposure = NULL,
  EMint = NULL,
  basec = NULL,
  basecval = NULL,
  ymreg = "coxph",
  astar = NULL,
  a = NULL,
  nboot = 200,
  bh_method = "breslow",
  s = NULL,
  multistate_seed = 123,
  n_workers = NULL
)

Arguments

data

a data frame (or object coercible by as.data.frame to a data frame) containing the variables in the model.

outcome

variable name of the outcome.

yevent

variable name of the event for the outcome.

mediator

variable name of the mediator.

mevent

Event indicator for the mediator in multistate modeling.

exposure

variable name of the exposure.

EMint

a logical value. TRUE indicates there is exposure-mediator interaction in yreg.

basec

a vector of variable names of the confounders.

basecval

(required when estimation is paramfunc and EMint is TRUE) a list of values at which each confounder is conditioned on, following the order in basec. If NULL, the mean of each confounder is used.

ymreg

type of multistate survival model to be used. Currently supporting coxph only.

astar

the control value of the exposure.

a

the treatment value of the exposure.

nboot

(used when inference is bootstrap) the number of bootstraps applied. Default is 200.

bh_method

Method for estimating baseline hazards in multistate modeling. Currently supporting "breslow" only.

s

The time point(s) beyond which survival probability is interested in multistate modeling.

multistate_seed

The seed to be used when generating bootstrap datasets for multistate modeling.

Value

The output is a list that consists of 4 elements:

  • the model summary of the joint multistate Cox proportional hazards model fitted on the original dataset

  • the point estimates of RD and SD for each of the user-specified time points of interest on the original dataset

  • the summary of the bootstrapped RD, SD, and TE estimates for each of the user-specified time point of interest, including the 2.5, 50, and 97.5th percentiles

  • the estimated RD, SD, TD for each of the user-specified time point of interest for each bootstrap dataset

Details

Assumptions of the multistate method

  • Consistency of potential outcomes: For each i and each t, the survival in a world where we intervene, i.e., setting the time to treatment to a specific value t (via a fixed or stochastic intervention) is the same as the survival in the real world where we observe a time to treatment equal to t.

  • There is no unmeasured mediator-outcome confounding: Given exposure and basec, mediator is independent of outcome.

  • Non-informative censoring of event times: The observed censoring time is conditionally independent of all potential event times.

  • Positivity: Each exposure-covariate combination has a non-zero probability of occurring.

References

Valeri L, Proust-Lima C, Fan W, Chen JT, Jacqmin-Gadda H. A multistate approach for the study of interventions on an intermediate time-to-event in health disparities research. Statistical Methods in Medical Research. 2023;32(8):1445-1460.

Examples

if (FALSE) { library(CMAverse) multistate_out = cmest_multistate(data = sc_data, s = s_vec, multistate_seed = 1, exposure = 'A', mediator = 'M', outcome = 'S', yevent = "ind_S", mevent = "ind_M", basec = c("C1", "C2"), basecval = c("C1" = "1", "C2" = as.character(mean(sc_data$C2))), astar="0", a="1", nboot=1, EMint=F, bh_method = "breslow") multistate_out }