randomization_test: Fast randomization test
In fastrerandomize: Hardware-Accelerated Rerandomization for Improved Balance

randomization_test

R Documentation

Fast randomization test

Description

Fast randomization test

Usage

randomization_test(
  obsW = NULL,
  obsY = NULL,
  X = NULL,
  alpha = 0.05,
  candidate_randomizations = NULL,
  candidate_randomizations_array = NULL,
  n0_array = NULL,
  n1_array = NULL,
  randomization_accept_prob = 1,
  findFI = FALSE,
  c_initial = 2,
  max_draws = 10^6,
  batch_size = 10^5,
  randomization_type = "monte_carlo",
  approximate_inv = TRUE,
  file = NULL,
  verbose = TRUE,
  conda_env = "fastrerandomize",
  conda_env_required = TRUE
)

Arguments

`obsW`	A numeric vector where `0`'s correspond to control units and `1`'s to treated units.
`obsY`	An optional numeric vector of observed outcomes. If not provided, the function assumes a NULL value.
`X`	A numeric matrix of covariates.
`alpha`	The significance level for the test. Default is `0.05`.
`candidate_randomizations`	A numeric matrix of candidate randomizations.
`candidate_randomizations_array`	An optional 'JAX' array of candidate randomizations. If not provided, the function coerces `candidate_randomizations` into a 'JAX' array.
`n0_array`	An optional array specifying the number of control units.
`n1_array`	An optional array specifying the number of treated units.
`randomization_accept_prob`	An numeric scalar or vector of probabilities for accepting each randomization.
`findFI`	A logical value indicating whether to find the fiducial interval. Default is FALSE.
`c_initial`	A numeric value representing the initial criterion for the randomization. Default is `2`.
`max_draws`	An integer specifying the maximum number of candidate randomizations to generate (or to consider) for the test when `randomization_type = "monte_carlo"`. Default is `1e6`.
`batch_size`	An integer specifying the batch size for Monte Carlo sampling. Batches are processed one at a time for memory efficiency. Default is `1e5`.
`randomization_type`	A string specifying the type of randomization for the test. Allowed values are "exact" or "monte_carlo". Default is "monte_carlo".
`approximate_inv`	A logical value indicating whether to use an approximate inverse (diagonal of the covariance matrix) instead of the full matrix inverse when computing balance metrics. This can speed up computations for high-dimensional covariates. Default is `TRUE`.
`file`	A character string specifying the path (including filename) where candidate randomizations will be saved or loaded from. If `NULL`, randomizations remain in memory. Default is NULL.
`verbose`	A logical value indicating whether to print progress information. Default is `TRUE`.
`conda_env`	A character string specifying the name of the conda environment to use via `reticulate`. Default is `"fastrerandomize"`.
`conda_env_required`	A logical indicating whether the specified conda environment must be strictly used. If `TRUE`, an error is thrown if the environment is not found. Default is `TRUE`.

Value

Returns an S3 object with slots:

p_value A numeric value or vector representing the p-value of the test (or the expected p-value under the prior structure specified in the function inputs).
FI A numeric vector representing the fiducial interval if findFI=TRUE.
tau_obs A numeric value or vector representing the estimated treatment effect(s).
fastrr_env The fastrerandomize environment.

References

Zhang, Y. and Zhao, Q., 2023. What is a randomization test?. Journal of the American Statistical Association, 118(544), pp.2928-2942.

Examples

## Not run: 
# A small synthetic demonstration with 6 units, 3 treated and 3 controls:

# Generate pre-treatment covariates
X <- matrix(rnorm(24*2), ncol = 2)

# Generate candidate randomizations
RandomizationSet_MC <- generate_randomizations(
  n_units = nrow(X),
  n_treated = round(nrow(X)/2),
  X = X,
  randomization_accept_prob = 0.1,
  randomization_type = "monte_carlo",
  max_draws = 100000,
  batch_size = 1000
)

# Generate outcome
W <- RandomizationSet_MC$randomizations[1,]
obsY <- rnorm(nrow(X), mean = 2 * W)

# Perform randomization test
results_base <- randomization_test(
  obsW = W,
  obsY = obsY,
  X = X,
  candidate_randomizations = RandomizationSet_MC$randomizations,
)
print(results_base)

# Perform randomization test
result_fi <- randomization_test(
  obsW = W,
  obsY = obsY,
  X = X,
  candidate_randomizations = RandomizationSet_MC$randomizations,
  findFI = TRUE
)
print(result_fi)

## End(Not run)

fastrerandomize documentation built on April 4, 2025, 5:10 a.m.