causal.estimate: Estimate causal effects using FLEXOR, IC, or IGO methods

In WMAP: Weighted Meta-Analysis with Pseudo-Populations

Estimate causal effects using FLEXOR, IC, or IGO methods

Description

This function estimates causal effects based on the specified pseudo-population method. The FLEXOR method involves an iterative two-step procedure.

Usage

causal.estimate(
  S,
  Z,
  X,
  Y,
  B = 0,
  method,
  naturalGroupProp = NULL,
  num.random = 40,
  gammaMin = 0.001,
  gammaMax = (1 - 0.001),
  seed = NULL,
  verbose = TRUE,
  parallel = FALSE,
  n_cores = NULL,
  outcome_model = FALSE,
  crossfit_folds = NULL
)

Arguments

S	Vector of factor levels representing the study memberships. Takes values in {1, ..., J}.
Z	Vector of factor levels representing the group memberships. Takes values in {1, ..., K}.
X	Covariate matrix of N rows and p columns.
Y	Matrix of L outcomes, with dimensions N \times L.
B	Number of bootstrap samples for variance estimation. Default is 0 (point estimates only).
method	Pseudo-population method, i.e., weighting method. Take values in FLEXOR, IC, or IGO.
naturalGroupProp	Relevant only for FLEXOR method: a fixed user-specified probability vector \theta.
num.random	Relevant only for FLEXOR method: number of random starting points of \gamma in the two-step iterative procedure. Default is 40.
gammaMin	Relevant only for FLEXOR method: Lower bound for each \gamma_s in the two-step iterative procedure. Default is 0.001.
gammaMax	Relevant only for FLEXOR method: Upper bound for each \gamma_s in the two-step iterative procedure. Default is 0.999.
seed	Seed for random number generation. Default is NULL.
verbose	Logical; if TRUE (default), displays progress messages during computation to the console. Set to FALSE to suppress these messages.
parallel	Logical; if TRUE, use parallel processing for bootstrap (default: FALSE)
n_cores	Number of cores to use for parallel bootstrap (default: availableCores() - 1). Only used if parallel = TRUE.
outcome_model	Logical; if TRUE, fits a random forest on X, S, Z and substitutes predicted outcomes for observed Y. Default FALSE.
crossfit_folds	Integer >= 2 for K-fold cross-fitting of the outcome model, or NULL (default) to fit on the full data. Only used when outcome_model = TRUE.

Value

An S3 object of class causal_estimates with the following components:

percentESS

Percentage sample ESS of the pseudo-population.

moments.ar

Array of dimension 3 \times K \times L: estimated means, SDs, and medians (dim 1) for K groups (dim 2) and L outcomes (dim 3).

otherFeatures.v

Estimated mean group differences for L outcomes.

collatedMoments.ar

Array of dimension 3 \times K \times L \times B: moments.ar for each of B bootstrap samples (only present when B > 0).

collatedOtherFeatures.mt

Matrix of dimension L \times B: otherFeatures.v for each of B bootstrap samples (only present when B > 0).

collatedESS

Vector of length B: percentage sample ESS for each bootstrap sample (only present when B > 0).

method

Weighting method used (FLEXOR, IC, or IGO).

selected_nodesize

Selected min.node.size for the propensity forest.

diagnostics

A list of propensity model diagnostics:

• frac_truncated: Fraction of subjects with own-cell propensity below the truncation floor prior to stabilization.

• crossfit_accuracy: Out-of-fold classification accuracy of the propensity model.

• max_weight: Maximum weight prior to normalization.

• prob_quantiles: Quantiles of the subject-level propensity distribution.

Examples

data(demo)

# Point estimates only (no CIs)
result <- causal.estimate(S, Z, X, Y, B = 0, method = "IC", naturalGroupProp)
summary(result)

# Bootstrap CIs
set.seed(1)
result <- causal.estimate(S, Z, X, Y, B = 100, method = "IC", naturalGroupProp)
summary(result)
plot(result)

# FLEXOR method
result <- causal.estimate(S, Z, X, Y, B = 100, method = "FLEXOR", naturalGroupProp,
                           num.random = 40, seed = 1)

# Outcome model: substitute RF predictions for observed Y
result <- causal.estimate(S, Z, X, Y, B = 0, method = "FLEXOR", naturalGroupProp,
                           outcome_model = TRUE)

# Parallel bootstrap
result <- causal.estimate(S, Z, X, Y, B = 100, method = "FLEXOR", naturalGroupProp,
                           parallel = TRUE, n_cores = 2)

WMAP documentation built on Oct. 6, 2026, 1:07 a.m.