mcee: Mediated Causal Excursion Effects for MRTs (streamlined)

In MRTAnalysis: Assessing Proximal, Distal, and Mediated Causal Excursion Effects for Micro-Randomized Trials

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
)

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.

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.

See Also

summary.mcee_fit, mcee_general, mcee_userfit_nuisance

Examples

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)

MRTAnalysis documentation built on Sept. 9, 2025, 5:41 p.m.