Package {WMAP}

Calculate balancing weights with method routing

Description

Compute balancing weights using IC, IGO, or FLEXOR methods.

Usage

Stage1(
  data,
  parm,
  method,
  flexorFlag,
  num.random,
  naturalGroupProp,
  gammaMin,
  gammaMax,
  verbose
)

Arguments

Value

List with two elements:

• return.parm - Updated parameter list with weights and ESS

• percentESS - Percentage effective sample size

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

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)

Bootstrap procedure for variance estimation

Description

Bootstrap procedure for variance estimation

Usage

bootStrap(
  data,
  moments.ar,
  moreFeatures.v,
  B,
  method,
  method_wt.v,
  naturalGroupProp,
  num.random.b,
  gammaMin,
  gammaMax,
  seed,
  verbose,
  parallel = FALSE,
  n_cores = NULL,
  outcome_model = FALSE,
  crossfit_folds = NULL,
  nodesize = NULL
)

Arguments

Value

List with three elements:

• collatedMoments.ar - Array of bootstrap moments

• collatedMoreFeatures.mt - Matrix of bootstrap mean differences

• collatedESS - Vector of bootstrap ESS values

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

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 bth 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 bth 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)

Check if factor levels are valid

Description

Validates that factor levels are exactly 1, 2, ..., num

Usage

check.factor(factor.vec, num)

Arguments

Value

Logical: TRUE if factor levels are invalid, FALSE if valid

Validate and resample bootstrap data

Description

Validate and resample bootstrap data

Usage

checkSample(data.in, wt_in.v)

Arguments

Value

Resampled data list with updated indices

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)

Function for FLEXOR optimization

Description

Function for FLEXOR optimization

Usage

fn.ESS_FLEXOR(sub_gamma_s, theta_z, parm, data)

Arguments

Value

Negative normalized ESS (scalar value to minimize)

Estimate multiple propensity scores

Description

Wrapper that calls fn.RF_ZFirst and prepares propensity scores for use in weight calculations.

Usage

fn.Estimate_mgPS(data, nodesize = NULL)

Arguments

Value

Parameter list with propensity scores:

• tmp.ar - Truncated propensity scores, dim (N, K, J)

• tmp1.ar - Negative log propensities (for weight calculation)

• e$sz - Joint propensity scores after truncation

• selected_nodesize - min.node.size used

• diagnostics - List with frac_truncated and prob_quantiles

Calculate FLEXOR weights

Description

Wrapper function that calls the iterative optimization loop to maximize effective sample size

Usage

fn.FLEXOR(start_theta_z, start_gamma_s, data, parm)

Arguments

Value

Updated parm with FLEXOR weights and convergence info

Calculate IC weights

Description

Calculate IC weights

Usage

fn.IC(theta_z, gamma_s, data, parm)

Arguments

Value

Updated parm with:

• wt.v - Weight vector (normalize to mean 1)

• ESS - Effective sample size

• gamma_s - Study probability used

• theta_z - Group probabilities used

Calculate IGO weights

Description

Calculate IGO weights

Usage

fn.Omnibus(theta_z, gamma_s, data, parm)

Arguments

Value

Updated parm with weights, ESS, and parameters

Calculate the weighted quantile using probability mass function

Description

Computes a quantile of discrete weighted distribution by constructing the cumulative distribution function from probability masses

Usage

fn.PMF_quantile(val, q, mass)

Arguments

Value

Numeric quantile value. For the minimum value, returns that value. Otherwise, returns the average of adjacent values for smoothness.

Estimate joint propensity scores with cross-fitting or single fit

Description

When nodesize = NULL (original data), generates 5-fold assignments, runs fn.RF_tune_nodesize to select min.node.size and obtain out-of-fold propensity scores in one pass. When nodesize is supplied (bootstrap), skips tuning and fits one ranger model on the full data instead.

Usage

fn.RF_ZFirst(data, svdCutoff, nodesize = NULL)

Arguments

Value

Parameter list with propensity scores:

• e$sz - P(S=s, Z=z | X) after truncation, dim (N, K, J)

• selected_nodesize - min.node.size used for the final fit

• diagnostics - List with frac_truncated, prob_quantiles, and crossfit_accuracy

Run one complete 5-fold cross-fit for propensity score estimation

Description

For each fold, fits a joint (S,Z) ranger probability forest on the training folds and predicts on the held-out fold. Returns out-of-fold joint propensity scores.

Usage

fn.RF_crossfit_once(data, matX2, min.node.size, fold_ids)

Arguments

Value

Array of dim (N, K, J): out-of-fold P(S=s, Z=z | X_i). Columns of the intermediate matrix are ordered by factor level: (s=1,z=1), (s=1,z=2), ..., (s=J,z=K), matching column index (s-1)*K + z.

Single-fit propensity score estimation for bootstrap samples

Description

Fits one joint (S,Z) ranger probability forest on the full (bootstrap) data and returns in-sample predictions.

Usage

fn.RF_fit_single(data, matX2, min.node.size)

Arguments

Value

Array of dim (N, K, J): in-sample P(S=s, Z=z | X_i)

Select min.node.size for propensity RF via weight-stability criteria

Description

Evaluates each candidate in c(10, 25, 50, 100) using 5-fold cross-fitted propensity scores (same fold assignments across candidates) and selects the smallest value that satisfies all three weight-stability criteria. The out-of-fold predictions for the selected candidate are returned directly as the final propensity scores. If no candidate passes, uses 100 and issues a warning.

Usage

fn.RF_tune_nodesize(data, matX2, fold_ids)

Arguments

Value

Named list with:

• nodesize - Selected min.node.size (integer)

• e_sz - Out-of-fold propensity array, dim (N, K, J)

• crossfit_accuracy - Proportion of subjects correctly classified by argmax of OOF predictions

Perform SVD dimensionality reduction on covariates

Description

Perform SVD dimensionality reduction on covariates

Usage

fn.SVD(data, cutoff)

Arguments

Value

Reduced-dimension covariate matrix with same dimensions as original

Calculate weighted moments and group differences

Description

Calculate weighted moments and group differences

Usage

fn.Stage2(local_data, local_wt.v, Y_hat = NULL, outcome_model = FALSE)

Arguments

Value

List with two elements:

• moments.ar - Array (3 * K * L) of means, SDs, medians

• moreFeatures.v - Vector (length L) of mean differences

Wrapper for Stage1 function with retry logic

Description

Wrapper for Stage1 function with retry logic

Usage

fn.Weights(
  data,
  method,
  flexorFlag,
  num.random,
  naturalGroupProp,
  gammaMin,
  gammaMax,
  verbose,
  nodesize = NULL
)

Arguments

Value

List with return.parm and percentESS, or NULL if all attempts fail

Check for low effective sample size

Description

Warns if the percentage ESS falls below a threshold, indicating that the psuedo-population weights may be unreliable.

Usage

fn.check_ess(percentESS, threshold = DIAG_ESS_THRESHOLD)

Arguments

Value

Invisibly returns TRUE if warning issued, FALSE otherwise

Check for extreme weights

Description

Warns if any weights are excessively large relative to the mean, which can indicate positivity violations or model misspecification.

Usage

fn.check_extreme_weights(wt.v, ratio_threshold = DIAG_WEIGHT_RATIO)

Arguments

Value

Invisibly returns TRUE if warning issued, FALSE otherwise

Check for positivity violations

Description

Warns if any study-group combination has very few observations or estimated propensities near zero, suggesting positivity may be violated.

Usage

fn.check_positivity(data, parm, propensity_min = DIAG_PROPENSITY_MIN)

Arguments

Value

Invisibly returns TRUE if warning issued, FALSE otherwise

Clip vector values to bounds and renormalize

Description

Ensures all values are within specified bounds and sum to 1

Usage

fn.clip(vec, gammaMin, gammaMax)

Arguments

Value

Clipped and renormalized vector that sums to 1

Create structured data list from input vectors

Description

Converts raw input vectors into a structured list format used throughout the package

Usage

fn.createListData(S, Z, X, Y = NULL)

Arguments

Value

Structured list containing:

• S, Z, X, Y - Original inputs

• N - Total sample size

• J - Number of studies

• K - Number of groups

• p - Number of covariates

• Plus all components added by preStage1()

Fit random forest outcome model and generate predicted outcomes

Description

Fits a random forest regressor for each outcome column using covariates X, study membership S, and group membership Z. Predicts each subject's outcome under their actual group. These predictions are used in fn.Stage2 when outcome_model = TRUE.

Usage

fn.fit_outcome_model(data, crossfit_folds = NULL)

Arguments

Value

Matrix of dimension N \times L of predicted outcomes. Y_hat[i, l] is the predicted outcome for individual i under their actual group for outcome l.

Iterative optimization loop for FLEXOR

Description

Iterative optimization loop for FLEXOR

Usage

fn.loop(
  start_theta_z,
  start_gamma_s,
  data,
  parm,
  FUN,
  FUN2,
  tol = 0.001,
  optim.maxit = 2,
  loop.maxit = 50
)

Arguments

Value

Updated parm with:

• wt.v - Optimized weights

• ESS - Final effective sample size

• gamma_s - Optimized study probabilities

• theta_z - Group probailities (unchanged)

• count - Number of iterations performed

• change - Final relative ESS change

Sample from Dirichlet distribution

Description

Sample from Dirichlet distribution

Usage

fn.rdirichlet(alpha)

Arguments

Value

Numeric vector sampled from Dirichlet(alpha)

Run all diagnostic checks on balancing weights

Description

Convenience wrapper that runs ESS, extreme weight, and positivity checks. Called automatically by balancing.weights() and causal.estimate().

Usage

fn.run_diagnostics(wt.v, percentESS, data, parm = NULL)

Arguments

Value

Invisibly returns named logical vector of which warnings were issued

Validate method and FLEXOR-specific parameters

Description

Checks that the selected method is valid and that FLEXOR parameters meet required constraints

Usage

fn.userInputChecks_1(
  method,
  flexorFlag,
  gammaMin,
  gammaMax,
  num.random,
  naturalGroupProp
)

Arguments

Value

NULL (stops with error if validation fails)

Validate data dimensions and completeness

Description

Checks that S, Z, X dimensions match and that there are no missing values

Usage

fn.userInputChecks_2(data, B = NULL)

Arguments

Value

NULL (stops with error if validation fails)

Variable outcome dimensions

Description

Checks that Y dimensions match S

Usage

fn.userInputChecks_3(data)

Arguments

Value

NULL (stops with error if validation fails)

Global variable declarations for R CMD check

Description

These variables are created using the zeallot package;s which allows multiple assignment. Declaring them here prevents R CMD check warnings about undefined globals.

Null coalescing operator Returns first argument if not NULL, otherwise returns second argument

Description

Null coalescing operator Returns first argument if not NULL, otherwise returns second argument

Usage

a %||% b

Check if value is a natural number

Description

Check if value is a natural number

Usage

is.natural(x, tol = .Machine$double.eps^0.5)

Arguments

Value

Logical indicating if x is a natural number (positive integer)

Check if vector is a valid probability vector

Description

Tests if values are non-negative and sum to 1 (within tolerance)

Usage

is.probvector(x, tol = .Machine$double.eps^0.5)

Arguments

Value

Logical indicating if x is a natural number (positive integer)

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

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)

Preprocess data for Stage 1 analysis

Description

Creates an index lists and counts for each study-group combination, which are used throughout the weighting calculations

Usage

preStage1(data.local)

Arguments

Value

Updated data list with added components:

• N.sz - Matrix of counts for each study-group combination

• indx.sz.lst - List of indices for each study-group combination

• N.z - Total count per group

• N.s - TOtal count per study

• which.binary - Indices of binary covariates

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

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

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)

Format estimates with confidence intervals

Description

Creates formatted strings displaying point estimates with their confidence intervals in the format: "estimate (lower, upper)"

Usage

write_res(estimates, CI)

Arguments

Value

Character vector of formatted estimates with CIs

Calculate standard deviation ratios with confidence intervals

Description

Calculate standard deviation ratios with confidence intervals

Usage

write_sigma_ratio(output)

Arguments

Value

Character vector of formatted SD ratios with 95