Package 'WMAP'

Compute balancing weights using FLEXOR, IC, or IGO methods

Description

This function calculates balancing weights based on the specified pseudo-population method.

Usage

balancing.weights(
  S,
  Z,
  X,
  method,
  naturalGroupProp,
  num.random = 40,
  gammaMin = 0.001,
  gammaMax = (1 - 0.001),
  seed = NULL,
  verbose = TRUE,
  suppress_diagnostics = FALSE,
  nodesize = 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.
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; Relevant only for FLEXOR method: if TRUE (default), displays progress messages during computation to the console. Set to FALSE to suppress these messages.
suppress_diagnostics	Logical; if TRUE, suppress diagnostic warnings (default: FALSE). Used internally during bootstrapping to avoid console clutter.
nodesize	Integer nodesize for the propensity score random forests; if NULL, selected automatically. Used internally during bootstrapping to reuse the nodesize from the original data.

Value

An S3 list object with the following components:

wt.v

$N$ empirically normalized sample weights.

percentESS

Percentage sample effective sample size (ESS) for the pseudo-population.

Examples

data(demo)

# IC Method
weights_ic <- balancing.weights(S, Z, X, method = "IC", naturalGroupProp)
summary(weights_ic)

# IGO Method
weights_igo <- balancing.weights(S, Z, X, method = "IGO", naturalGroupProp)
summary(weights_igo)

# FLEXOR Method
weights_flexor <- balancing.weights(S, Z, X, method = "FLEXOR", naturalGroupProp, num.random = 40)
summary(weights_flexor)

---

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 list object with the following components:

percentESS

Percentage sample effective sample size (ESS) of the pseudo-population.

moments.ar

An array of dimension $3 \times K \times L$, containing:

• Estimated means, standard deviations (SDs), and medians (dimension 1),

• For $K$ groups (dimension 2),

• And $L$ outcomes (dimension 3).

otherFeatures.v

Estimated mean group differences for $L$ outcomes.

collatedMoments.ar

An array of dimension $3 \times K \times L \times B$, containing:

• moments.ar of the $b$th bootstrap sample (dimensions 1–3),

• For $B$ bootstrap samples (dimension 4).

collatedOtherFeatures.mt

A matrix of dimension $L \times B$ containing:

• otherFeatures.v of the $b$th bootstrap sample (dimension 1),

• For $B$ bootstrap samples (dimension 2).

collatedESS

A vector of length $B$

containing percentage sample ESS for $B$ bootstrap samples.

method

Pseudo-population method, i.e., weighting method.

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)

---

Demo Dataset

Description

A dataset containing example data for demonstration purposes.

Usage

data(demo)

Format

An rda object, with 450 observations and the following variables:

S

A vector of factor levels, representing the study memberships.

Z

A vector of factor levels, representing the group memberships.

X

A covariate matrix.

Y

An outcome matrix.

naturalGroupProp

The relative group prevalences of the larger natural population. Necessary only for FLEXOR weights; it should be skipped for IC and IGO weights.

groupNames

Disease subtype names "IDC" or "ILC"

Details

Demo Dataset for WMAP Examples

A demonstration dataset containing multi-site, multi-group observational data for testing WMAP weighting methods. The data simulates a study of breast cancer subtypes across mutliple hospitals.

See Also

balancing.weights for computing weights causal.estimate for estimating causal effects

Examples

# Load the demo dataset

data(demo)

# Examine the structure
str(S) # Study memberships
str(Z) # Group memberships
table(S, Z) # Cross-tabulation of studies and groups

# Basic usage with IC method
weights <- balancing.weights(S, Z, X, method = "IC", naturalGroupProp)
summary(weights)

# Full causal analysis
results <- causal.estimate(S, Z, X, Y, B = 10, method = "IC", naturalGroupProp)
summary(results)
plot(results)

---

Plot method for objects of class 'causal_estimates'

Description

Creates a boxplot showing the distribution of effective sample size (ESS) across bootstrap samples for the specified weighting method.

Usage

## S3 method for class 'causal_estimates'
plot(x, ...)

Arguments

x	An object of class 'causal_estimates' returned by causal.estimate().
...	Additional arguments: y_limit The y-axis range. Default is c(0,50). color The boxplot color. Default is "red".

Value

A boxplot of percent sample ESS for a specific weighting method (FLEXOR, IC, or IGO

Examples

## Not run: 
data(demo)
result <- causal.estimate(S, Z, X, Y, B = 5, method = "FLEXOR", naturalGroupProp)
plot(result)
plot(result, y_limit = c(0, 100), color = "steelblue")

## End(Not run)

---

Summary method for objects of class 'balancing_weights'

Description

Displays a summary of balancing weights including the numnber of weights. their distribution, and the effective sample size.

Usage

## S3 method for class 'balancing_weights'
summary(object, ...)

Arguments

object	An object of class 'balancing_weights' returned by balancing.weights().
...	Additional arguments (currently unused, reserved for future extensions).

Value

No return value, called for side effects (prints summary to console)

• The total number of weights

• Statistical summary of weight values

• Percentage sample effective sample size (ESS) for the pseudo-population

Examples

data(demo)
result <- balancing.weights(S, Z, X, method = "IC", naturalGroupProp)
summary(result)

---

Summary method for objects of class 'causal_estimates'

Description

Displays a comprehensive summary of causal estimates including effective sample size, mean differences between groups with confidence intervals, and standard deviation ratios.

Usage

## S3 method for class 'causal_estimates'
summary(object, ...)

Arguments

object	An object of class 'causal_estimates' returned by causal.estimate()
...	Additional arguments (currently unused, reserved for future extensions).

Value

No return value, called for side effects (prints summary to console):

• Percentage sample effective sample size (ESS) for the pseudo-population

• The mean differences between two groups with their corresponding 95

• The ratios of standard deviations between two groups with their corresponding 95

Examples

data(demo)

set.seed(1)
result <- causal.estimate(S, Z, X, Y, B = 5, method = "IC", naturalGroupProp)
summary(result)

---