Package 'MRStdLCRT'

Model-robust standardization for longitudinal cluster-randomized trials

Description

Fits unadjusted and augmented (model-robust standardization) estimators for four longitudinal cluster-randomized trial (L-CRT) estimands, with inference based on leave-one-cluster-out (delete-1) jackknife standard errors.

Usage

mrstdlcrt_fit(
  data,
  formula,
  cluster_id = "cluster",
  period = "period",
  trt = "trt",
  method = c("gee", "lmer", "glmer"),
  family = c("gaussian", "binomial"),
  corstr = "independence",
  scale = c("RD", "RR", "OR")
)

Arguments

data	A data.frame containing the outcome, trt, period, cluster_id, and any covariates appearing in formula.
formula	A model formula for the working model. May include interactions and (for "lmer"/"glmer") random effects terms. For "gee", random effects terms are removed prior to fitting.
cluster_id	Character string giving the cluster identifier column name.
period	Character string giving the period identifier column name. May be numeric, integer, or a factor; ordering is taken from the natural order of the column.
trt	Character string giving the binary treatment column name (0/1).
method	Working model fitting method: "gee", "lmer", or "glmer".
family	Outcome family: "gaussian" for continuous outcomes or "binomial" for binary outcomes.
corstr	Correlation structure passed to gee when method = "gee" (e.g., "independence", "exchangeable", "ar1").
scale	For family = "binomial" only: "RD" (risk difference), "RR" (log risk ratio), or "OR" (log odds ratio).

Details

The four supported estimands are:

h-iATE

Horizontal individual average treatment effect (individual-weighted within each period).

h-cATE

Horizontal cluster average treatment effect (cluster-weighted within each period).

v-iATE

Vertical individual average treatment effect (period-weighted; individuals weighted within period).

v-cATE

Vertical cluster-period average treatment effect (period-weighted; cluster-period cells equally weighted within period).

For each estimand, the function returns point estimates under:

1. an unadjusted estimator based on cluster-period means, and

2. an augmented estimator that combines model-based counterfactual predictions with a design-based correction term (model-robust standardization).

Data structure. The input data must contain: (i) a cluster identifier cluster_id, (ii) a period identifier period, (iii) a binary treatment indicator trt coded as 0/1 (or coercible to 0/1), and (iv) the outcome appearing on the left-hand side of formula.

Treatment must be constant within cluster-period. Within each (cluster, period) cell, trt is required to be constant; otherwise the function errors and prints example problematic cells.

Automatic period inclusion (mixture rule). Marginal means and treatment contrasts are aggregated using only “mixed” periods—periods in which both treated and control clusters are observed. Periods with all clusters in the same arm contribute no information to between-arm contrasts and are excluded automatically.

Working model options.

method = "lmer"

Linear mixed model via lme4 for continuous outcomes.

method = "glmer"

Logistic mixed model via lme4 for binary outcomes.

method = "gee"

Generalized estimating equations via gee. Random-effects terms in formula (e.g., (1|cluster)) are ignored automatically.

For family = "binomial", treatment effects can be reported on the risk-difference scale (scale = "RD"), log risk-ratio scale (scale = "RR"), or log odds-ratio scale (scale = "OR"). For family = "gaussian", effects are mean differences (and scale is ignored).

Inference. Standard errors are computed using a delete-1 cluster jackknife: refit the procedure leaving out one cluster at a time, compute the jackknife covariance, and report per-estimand jackknife SEs. Downstream methods summary and plot use t-critical values with df = I - 1, where I is the number of clusters.

Value

An object of class "mrs" with components:

estimates

A tibble of unadjusted and adjusted point estimates for the four estimands.

jk_se

A tibble of corresponding delete-1 cluster jackknife standard errors.

jk_cov_unadj, jk_cov_aug

Jackknife covariance matrices for unadjusted and adjusted estimators.

reps

Internal components used for fitting and aggregation (including kept periods and mixture table).

meta

Metadata: call, method/family/scale, kept periods, cluster/period counts, etc.

The class has print, summary, and plot methods.

References

Fang, X. and Li, F. (2025). Model-Robust Standardization for Longitudinal Cluster-Randomized Trials. arXiv:2507.17190.

Examples

data(sw_c)

# Keep the example fast for R CMD check: use a small subset of clusters
cl_keep <- sort(unique(sw_c$cluster))[1:6]
dat <- sw_c[sw_c$cluster %in% cl_keep, ]

fit <- mrstdlcrt_fit(
  data = dat,
  formula = y ~ trt + factor(period) + x1 + x2 + (1 | cluster),
  cluster_id = "cluster",
  period = "period",
  trt = "trt",
  method = "lmer",
  family = "gaussian"
)

fit
summary(fit, show_counts = FALSE, ics = "none")
plot(fit)

---

Plot estimates from an mrs fit

Description

Plots unadjusted vs adjusted estimates with t-based confidence intervals computed from delete-1 cluster jackknife SEs (df = I - 1). Facets by estimand.

Usage

## S3 method for class 'mrs'
plot(x, level = 0.95, estimand = NULL, point_size = 2.8, ...)

Arguments

x	An object of class "mrs".
level	Confidence level.
estimand	Optional subset of estimands to plot.
point_size	Point size.
...	Unused.

Value

Invisibly returns a ggplot2 object.

Examples

data(sw_c)
dat <- sw_c[sw_c$cluster %in% sort(unique(sw_c$cluster))[1:6], ]

fit <- mrstdlcrt_fit(
  data = dat,
  formula = y ~ trt + factor(period) + x1 + x2 + (1 | cluster),
  cluster_id = "cluster", period = "period", trt = "trt",
  method = "lmer", family = "gaussian"
)

plot(fit)

---

Print method for mrs objects

Description

Print method for mrs objects

Usage

## S3 method for class 'mrs'
print(x, ...)

Arguments

x	An object of class "mrs".
...	Unused.

Value

x invisibly.

---

Summarize an mrs fit

Description

Prints key diagnostics (kept periods / mixture table), and per-estimand point estimates with delete-1 cluster jackknife SEs and t-based confidence intervals (df = I - 1). Optionally prints an ICS linear-contrast F-test.

Usage

## S3 method for class 'mrs'
summary(
  object,
  level = 0.95,
  estimand = NULL,
  digits = 6,
  show_counts = TRUE,
  ics = "global",
  ics_method = c("both", "unadjusted", "adjusted"),
  ics_tol = 1e-10,
  ...
)

Arguments

object	An object of class "mrs".
level	Confidence level for Wald-type confidence intervals.
estimand	Optional subset of estimands to print.
digits	Digits to print.
show_counts	If TRUE, print aggregation counts tables.
ics	ICS test specification. Use "global" (default) or "none" to disable. You may also pass a character vector, list spec, or numeric contrast matrix.
ics_method	Which covariance to use for ICS test: "both", "unadjusted", "adjusted".
ics_tol	Numerical tolerance for rank / generalized inverse.
...	Unused (accepts method_type= as alias for ics_method=).

Value

Invisibly returns a list containing printed tables/metadata and (if requested) ICS results.

Examples

data(sw_c)
dat <- sw_c[sw_c$cluster %in% sort(unique(sw_c$cluster))[1:6], ]

fit <- mrstdlcrt_fit(
  data = dat,
  formula = y ~ trt + factor(period) + x1 + x2 + (1 | cluster),
  cluster_id = "cluster", period = "period", trt = "trt",
  method = "lmer", family = "gaussian"
)

summary(fit, show_counts = FALSE, ics = "none")

---

Example stepped wedge CRT dataset with binary outcome

Description

A toy dataset with cluster, period, and individual records for illustrating estimands in stepped wedge CRT with a binary outcome.

Usage

data(sw_b)

Format

A data frame with columns:

cluster

Cluster identifier (integer).

period

Period index (integer).

id

Individual identifier within cluster-period (integer).

trt

Treatment indicator (0/1).

x1

Auxiliary covariate (0/1).

x2

Auxiliary covariate (numeric).

y

Outcome (0/1, binary).

Examples

data(sw_b)
head(sw_b)

---

Example of stepped wedge CRT dataset for continuous outcome

Description

A toy dataset with cluster, period, and individual records for illustrating estimands in stepped wedge CRT with a continuous outcome.

Usage

data(sw_c)

Format

A data frame with columns:

cluster

Cluster identifier (integer).

period

Period index (integer).

id

Individual identifier within cluster-period (integer).

trt

Treatment indicator (0/1).

x1

Auxiliary covariate (0/1).

x2

Auxiliary covariate (numeric).

y

Outcome (numeric, continuous).

Examples

data(sw_c)
head(sw_c)

---

Example crossover cluster-randomized trial dataset with binary outcome

Description

A small simulated 2×2 crossover trial dataset with a binary outcome.

Usage

xo_b

Format

A tibble/data.frame with one row per subject and the following columns:

h

Integer cluster ID (hospital)

p

Integer period (1 or 2)

k

Integer subject index within cluster-period

trt

Treatment indicator (0 = control, 1 = treatment)

x_c01, x_c02

Continuous covariates

x_b01

Binary covariate (0/1)

x_cat1_2, x_cat1_3

Dummy variables for a 3-level categorical covariate (level 1 is reference)

y_bin

Observed binary outcome (0/1)

Examples

data(xo_b)
str(xo_b)
head(xo_b)

---

Example crossover cluster-randomized trial dataset with continuous outcome

Description

A small simulated 2×2 crossover trial dataset with a continuous outcome.

Usage

xo_c

Format

A tibble/data.frame with one row per subject and the following columns:

h

Integer cluster ID (hospital)

p

Integer period (1 or 2)

k

Integer subject index within cluster-period

trt

Treatment indicator (0 = control, 1 = treatment)

x_c01, x_c02

Continuous covariates

x_b01

Binary covariate (0/1)

x_cat1_2, x_cat1_3

Dummy variables for a 3-level categorical covariate (level 1 is reference)

y_cont

Observed continuous outcome

Examples

data(xo_c)
str(xo_c)
head(xo_c)

---