mcee_userfit_nuisance: Mediated Causal Excursion Effects with user-supplied nuisance predictions

Description

Skips Stage-1 model fitting and uses user-provided nuisance predictions.

Usage

mcee_userfit_nuisance(
  data,
  id,
  dp,
  outcome,
  treatment,
  mediator,
  availability = NULL,
  time_varying_effect_form,
  p1,
  q1,
  eta1,
  eta0,
  mu1,
  mu0,
  nu1,
  nu0,
  weight_per_row = NULL,
  verbose = TRUE
)

Value

An "mcee_fit" object; see mcee.

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.
time_varying_effect_form: RHS-only formula for the basis \(f(t)\) (e.g., ~ 1, ~ dp, ~ poly(dp,2)).
p1, q1, eta1, eta0, mu1, mu0, nu1, nu0: Numeric vectors (or column names) of per-row predictions aligned with data. See Details for definitions.
weight_per_row: Optional numeric vector of row weights (nonnegative, length nrow(data)). If NULL, uniform within-id weights are used.
verbose: Logical; print progress messages.

Details

Nuisance definitions:

p1: \(P(A_t=1\mid H_t)\) (known in MRTs). (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\).)
q1: \(P(A_t=1\mid H_t, M_t)\). (Technically, this is \(P(A_t=I_t\mid H_t, M_t)\), but the user is allowed to input \(P(A_t=1\mid H_t, M_t)\) and the function will automatically correct it by setting q1 = 1 when \(I_t = 0\).)
eta1, eta0: \(E(Y\mid H_t, A_t=1)\) and \(E(Y\mid H_t, A_t=0)\).
mu1, mu0: \(E(Y\mid H_t, A_t=1, M_t)\) and \(E(Y\mid H_t, A_t=0, M_t)\).
nu1, nu0: cross-world regressions; see vignette and paper for definitions.

If availability is provided, rows with \(I=0\) are coerced to p1=q1=1 (and hence p0=q0=1); a warning is emitted if overrides occur.

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_usr <- mcee_userfit_nuisance(dat, "id","dp","Y","A","M",
    time_varying_effect_form = ~ dp,
    p1 = rep(0.5, nrow(dat)),
    q1 = runif(nrow(dat),.3,.7),
    eta1 = rnorm(nrow(dat)), eta0 = rnorm(nrow(dat)),
    mu1 = rnorm(nrow(dat)),  mu0 = rnorm(nrow(dat)),
    nu1 = rnorm(nrow(dat)),  nu0 = rnorm(nrow(dat)))