randomization_test {fastrerandomize}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:

References

See Also

generate_randomizations for randomization generation function.

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)


[Package fastrerandomize version 0.2 Index]