Begin a Rerandomization Search

This method creates an object of type rerandomization_experimental_design and will immediately initiate a search through allocation space for forced-balance designs. For debugging, you can use set the seed parameter and num_cores = 1 to be assured of deterministic output.

Usage

initRerandomizationExperimentalDesignObject(
  X = NULL,
  obj_val_cutoff_to_include,
  max_designs = 1000,
  objective = "mahal_dist",
  Kgram = NULL,
  wait = FALSE,
  start = TRUE,
  num_cores = 1,
  seed = NULL,
  verbose = TRUE,
  use_safe_inverse = FALSE
)

Arguments

X

The design matrix with $n$ rows (one for each subject) and $p$ columns (one for each measurement on the subject). This is the design matrix you wish to search for a more optimal design.

obj_val_cutoff_to_include

Only allocation vectors with objective values lower than this threshold will be returned. If the cutoff is infinity, you are doing BCRD and you should use the complete_randomization_with_forced_balanced function instead.

max_designs

The maximum number of designs to be returned. Default is 10,000. Make this large so you can search however long you wish as the search can be stopped at any time by using the stopSearch method

objective

The objective function to use when searching design space. This is a string with valid values "mahal_dist" (the default), "abs_sum_diff" or "kernel".

Kgram

If the objective = kernel, this argument is required to be an n x n matrix whose entries are the evaluation of the kernel function between subject i and subject j. Default is NULL.

wait

Should the R terminal hang until all max_designs vectors are found? The default is FALSE.

start

Should we start searching immediately (default is TRUE).

num_cores

The number of CPU cores you wish to use during the search. The default is 1.

seed

The set to set for deterministic output. This should only be set if num_cores = 1 otherwise the output will not be deterministic. Default is NULL for no seed set.

verbose

Should the algorithm emit progress output? Default is TRUE.

use_safe_inverse

Should a regularized inverse be used for the Mahalanobis objective? Default is FALSE.

Value

An object of type rerandomization_experimental_design_search which can be further operated upon.

Author

Adam Kapelner

Examples

if (FALSE) { # \dontrun{
set.seed(1)
X = matrix(rnorm(20), nrow = 10)
obj = initRerandomizationExperimentalDesignObject(
  X,
  max_designs = 5,
  num_cores = 1,
  objective = "abs_sum_diff",
  obj_val_cutoff_to_include = Inf,
  start = TRUE,
  wait = TRUE,
  verbose = FALSE
)
obj
} # }