mcee: Mediated Causal Excursion Effects for MRTs (streamlined)

Description

Estimates the Natural Direct Excursion Effect (NDEE; \(\alpha\)) and Natural Indirect Excursion Effect (NIEE; \(\beta\)) for distal outcomes in micro-randomized trials (MRTs). Assumes the randomization probability is known (via rand_prob) and fits all nuisance functions using the same learner specified by control_reg_method.

Usage

mcee(
  data,
  id,
  dp,
  outcome,
  treatment,
  mediator,
  availability = NULL,
  rand_prob,
  time_varying_effect_form,
  control_formula_with_mediator,
  control_reg_method = c("glm", "gam", "rf", "ranger", "sl"),
  weight_per_row = NULL,
  specific_dp_only = NULL,
  verbose = TRUE,
  SL.library = NULL
)

Value

An object of class "mcee_fit" with elements:

mcee_fit: list with alpha_hat, beta_hat, alpha_se, beta_se, varcov, alpha_varcov, beta_varcov.
nuisance_models: fitted Stage-1 models for p,q,eta,mu,nu.
nuisance_fitted: per-row fitted values for the nuisance functions.
meta: list with basis dimension, number of ids, per-id lengths, weights used.
call: the matched call.

Arguments

data: A data.frame in long format (one row per id-by-decision point).
id: Character. Column name for subject identifier.
dp: Character. Column name for decision point index (must increase strictly within subject).
outcome: Character. Column name for distal outcome (constant within subject).
treatment: Character. Column name for treatment (coded 0/1).
mediator: Character. Column name for mediator.
availability: Optional character. Column name for availability (0/1). If NULL, all rows are treated as available.
rand_prob: Either a column name in data or a scalar giving the known randomization probability \(P(A_t=1 \mid H_t)\). (Technically, this is \(P(A_t=I_t\mid H_t)\), but the user is allowed to input \(P(A_t=1\mid H_t)\) and the function will automatically correct it by setting p1 = 1 when \(I_t = 0\).)
time_varying_effect_form: RHS-only formula for the basis \(f(t)\) (e.g., ~ 1, ~ dp, ~ poly(dp,2)).
control_formula_with_mediator: RHS-only formula for control variables used in nuisance models that may include the mediator (the wrapper will drop the mediator internally for nuisances that must exclude it).
control_reg_method: Learner for nuisance fits: one of "glm", "gam", "rf", "ranger", "sl".
weight_per_row: Optional numeric vector of row weights (nonnegative, length nrow(data)). If NULL, uniform within-id weights are used.
specific_dp_only: Optional numeric vector of decision points to target; internally converted to weight_per_row.
verbose: Logical; print progress messages.
SL.library: Optional character vector of SuperLearner libraries (used when control_reg_method = "sl").

Details

Requirements: rows grouped by subject, strictly increasing dp within subject, no missing (NA/NaN/Inf) in relevant variables. If availability is supplied, the wrapper enforces at \(I=0\): \(p_1=q_1=1\) in the nuisances.

Examples

Run this code

set.seed(1)
n <- 10
T <- 4
id <- rep(1:n, each = T)
dp <- rep(1:T, times = n)
A <- rbinom(n * T, 1, 0.5)
M <- rbinom(n * T, 1, plogis(-0.2 + 0.3 * A + 0.1 * dp))
Y <- ave(0.5 * A + 0.6 * M + 0.1 * dp + rnorm(n * T), id)
dat <- data.frame(id, dp, A, M, Y)

fit <- mcee(dat, "id", "dp", "Y", "A", "M",
    time_varying_effect_form = ~1,
    control_formula_with_mediator = ~ dp + M,
    control_reg_method = "glm",
    rand_prob = 0.5, verbose = TRUE
)
summary(fit)