Package 'EDI'

Description

Precomputes and caches the sorted risk-set structure needed to evaluate the Cox partial-likelihood, score, and Hessian, so that repeated Newton-Raphson or L-BFGS fits on the same (X, y, dead) data (e.g. across bootstrap/randomization replicates of the treatment column, or successive estimate_only vs. full-variance calls) do not repeat the $O(n \log n)$ sort and event-time tabulation on every call. This is the unstratified counterpart of build_stratified_cox_data_cache_cpp; the returned cache is consumed by fast_coxph_regression_prebuilt_cpp, which implements the same Cox partial-likelihood as fast_coxph_regression and fast_coxph_regression_cpp.

Usage

build_cox_data_cache_cpp(X, y, dead)

Arguments

Details

Model. No fitting happens here; this function only prepares the single risk set (stratum) used by the Breslow-tied Cox partial likelihood

$\ell(\beta) = \sum_{k} \Big[ \big(\textstyle\sum_{i \in D_k} x_i\big)^\top \beta - d_k \log\!\big(\textstyle\sum_{j \in R_k} e^{x_j^\top \beta}\big) \Big],$

where $D_k$ is the set of subjects with an event at the $k$-th unique event time and $R_k$ is the risk set (all subjects with y >= that event time). See fast_coxph_regression for the full model, scale, and optimizer contract; this page documents only the cache construction.

What is cached. Internally builds a single CoxData record that: (1) sorts subjects by ascending y (observed/censoring time), breaking ties by placing events (dead == 1) before censored observations at the same time; (2) stores the sort-permuted y, dead, and row-major copy of X; and (3) tabulates the vector of unique event times and, for each, the number of tied events (event_counts), which drives the Breslow tie-handling correction in the partial-likelihood, score, and Hessian.

Input conventions. X is an $n \times p$ design matrix with one row per subject and no intercept column (Cox models are fit on the partial likelihood, which has no intercept). y is the observed time (event or censoring time), and dead is a 0/1 event indicator (1 = event, 0 = right-censored); both must have length $n$ matching nrow(X). Tied event times are handled via the Breslow approximation (via event_counts), not the exact (Cox) or Efron method. There is no support for left- or interval-censored data at this layer; classes with more general censoring (see supports_interval_or_left_censored_data() in InferenceEngine) bypass this cache and dispatch to icenReg instead. NA/non-finite values in X, y, or dead and negative values of y are not checked or handled at this layer; callers are responsible for filtering or imputing upstream.

Return value and object lifetime. Returns an externalptr (Rcpp::XPtr) wrapping a heap-allocated std::vector<CoxData> of length 1 (a single unstratified stratum), so that fast_coxph_regression_prebuilt_cpp can share the same stratified interface as the stratified cache. The pointer owns its memory (finalizer registered via XPtr(..., true)) and is freed automatically by R's garbage collector; it must not be serialized (e.g. via saveRDS) or reused after the R session that created it exits. The cache is immutable once built and safe to reuse across many calls to fast_coxph_regression_prebuilt_cpp as long as X, y, and dead have not changed; callers (e.g. InferenceCoxPH$private$cox_data_cache) are responsible for invalidating and rebuilding the cache when the treatment assignment or covariates change.

Complexity. $O(n \log n)$ for the sort plus $O(n)$ for the tabulation pass, where $n$ is the number of subjects; memory use is $O(np)$ for the row-major copy of X plus $O(n)$ for the sorted y/dead and event-time tables.

Value

An externalptr to a cached, sorted Cox risk-set representation of (X, y, dead), for use as the cox_data_xptr argument of fast_coxph_regression_prebuilt_cpp.

See Also

build_stratified_cox_data_cache_cpp for the stratified (multiple risk-set) analog, fast_coxph_regression_prebuilt_cpp for the fitting routine that consumes this cache, and fast_coxph_regression for the full Cox model documentation, including the partial-likelihood derivation, tie-handling, and references. Analogous Python API: lifelines CoxPHFitter.

Description

Precomputes and caches, per stratum, the sorted risk-set structure needed to evaluate the stratified Cox partial-likelihood, score, and Hessian, so that repeated Newton-Raphson or L-BFGS fits on the same (X, y, dead, strata) data (e.g. across bootstrap/randomization replicates of the treatment column) do not repeat the per-stratum sort and event-time tabulation on every call. This is the stratified counterpart of build_cox_data_cache_cpp; the returned cache is consumed by fast_coxph_regression_prebuilt_cpp, which implements the same partial-likelihood family as fast_coxph_regression and fast_coxph_regression_cpp, extended to sum the log-partial- likelihood, score, and Hessian across independent strata-specific risk sets while sharing a single regression coefficient vector $\beta$ across all strata (a shared-$\beta$, per-stratum-baseline-hazard stratified Cox model).

Usage

build_stratified_cox_data_cache_cpp(X, y, dead, strata)

Arguments

Details

Model. No fitting happens here; this function only partitions subjects into per-stratum risk sets and prepares each one for the Breslow-tied stratified Cox partial likelihood

$\ell(\beta) = \sum_{s} \sum_{k \in s} \Big[ \big(\textstyle\sum_{i \in D_{sk}} x_i\big)^\top \beta - d_{sk} \log\!\big(\textstyle\sum_{j \in R_{sk}} e^{x_j^\top \beta}\big) \Big],$

where the outer sum runs over strata $s$ (distinct baseline hazards), $D_{sk}$ is the set of subjects with an event at the $k$-th unique event time within stratum $s$, and $R_{sk}$ is the corresponding within-stratum risk set (subjects in stratum $s$ with y >= that event time). Risk sets never cross strata, so subjects are only ever compared to other subjects in the same stratum; $\beta$ is shared across strata while the baseline hazard is allowed to differ arbitrarily by stratum. See fast_coxph_regression for the unstratified model, scale, and optimizer contract; this page documents only the per-stratum cache construction.

What is cached. Subjects are grouped into strata by their integer strata label (via an ordered std::map<int, ...>, so strata are processed and stored in ascending label order). Within each stratum, a CoxData record is built exactly as in build_cox_data_cache_cpp: subjects are sorted by ascending y, ties broken by placing events before censored observations, and the per-stratum unique event times and tied-event counts (event_counts) are tabulated to drive the within-stratum Breslow tie-handling correction.

Input conventions. X is an $n \times p$ design matrix with one row per subject and no intercept column. y is the observed time (event or censoring time) and dead is a 0/1 event indicator (1 = event, 0 = right-censored); both have length $n$ matching nrow(X). strata is a length-$n$ integer vector of stratum (block/cluster) labels; labels need not be contiguous or start at 1, and a stratum with a single subject or with no observed events contributes an empty or degenerate risk set that carries no information to the partial likelihood, score, or Hessian (its rows are still stored, but they will not affect the fit). Callers are expected to have already dropped uninformative strata upstream (see get_informative_rows() in the stratified-Cox inference class) when that matters for numerical stability; this function does not filter strata itself. As with build_cox_data_cache_cpp, tied event times use the Breslow approximation, there is no support for left- or interval-censored data at this layer, and NA/non-finite values in X, y, dead, or strata are not checked or handled here.

Return value and object lifetime. Returns an externalptr (Rcpp::XPtr) wrapping a heap-allocated std::vector<CoxData> with one element per distinct stratum label (ordered ascending by label), consumed by fast_coxph_regression_prebuilt_cpp exactly like the length-1 vector returned by build_cox_data_cache_cpp. Lifetime, garbage-collection, and non-serializability semantics are identical to build_cox_data_cache_cpp: the cache is immutable once built and safe to reuse across repeated fits as long as X, y, dead, and strata have not changed; callers (e.g. InferenceStratifiedCoxPH$private$strat_cox_data_cache) are responsible for invalidating and rebuilding it when the treatment assignment, covariates, or stratification changes.

Complexity. $O(n \log(n/S))$ for the per-stratum sorts plus $O(n)$ for the tabulation passes, where $n$ is the number of subjects and $S$ is the number of distinct strata; memory use is $O(np)$ for the per-stratum row-major copies of X plus $O(n)$ for the sorted y/dead and event-time tables.

Value

An externalptr to a cached, per-stratum sorted Cox risk-set representation of (X, y, dead, strata), for use as the cox_data_xptr argument of fast_coxph_regression_prebuilt_cpp.

See Also

build_cox_data_cache_cpp for the unstratified (single risk-set) analog, fast_coxph_regression_prebuilt_cpp for the fitting routine that consumes this cache, and fast_coxph_regression for the full Cox model documentation, including the partial-likelihood derivation, tie-handling, and references. Analogous Python API: lifelines CoxPHFitter (stratified fits via the strata argument) and statsmodels duration models.

Description

Removes the per-user config file written by tune_EDI_for_this_machine (so the next library(EDI) starts from the package's built-in performance-policy defaults) and resets the in-session cold-start, warm-start, and optimizer-algorithm dispatch policies to those defaults right away.

Usage

clear_local_EDI_optimization()

Value

Invisibly, TRUE if a saved tuning existed and was removed, FALSE if there was none.

See Also

tune_EDI_for_this_machine, get_local_EDI_optimization.

Examples

clear_local_EDI_optimization()

Description

A fixed-sample-size DesignFixed in which each subject's treatment assignment $w_i$ is drawn independently as $w_i \stackrel{iid}{\sim} \mathrm{Bernoulli}(p)$, $i = 1, \dots, n$, where $p$ is prob_T. This is the classical Bernoulli (independent-coin-flip) randomized design: unlike DesignFixediBCRD (complete randomization), which fixes the number of treated subjects at exactly $\mathrm{round}(np)$, a Bernoulli design leaves the realized number of treated subjects $n_T = \sum_i w_i \sim \mathrm{Binomial}(n, p)$ random; the trade-off is independence across subjects (useful for some asymptotic/martingale arguments) at the cost of not guaranteeing exact balance, which can matter for small $n$ or for inference procedures (e.g. exact permutation tests over a fixed number of treated) that assume a fixed $n_T$.

Draw mechanism. draw_ws_raw(r) delegates to generate_permutations_bernoulli_cpp(), which fills an $n \times r$ matrix of independent $\mathrm{Bernoulli}(p)$ draws (one column per requested replicate, via a Mersenne Twister RNG seeded once per call from R's RNG state), so r replicate allocation vectors are generated with a single C++ call rather than r separate calls into R's own random-number generation. assign_w_to_all_subjects() draws a single such allocation (r = 1) and applies it to all subjects at once.

No exchange/balance search. Because subjects are treated independently, there is no optimization step analogous to DesignFixedGreedyDOptimal: covariates, if supplied, do not influence the assignment probabilities or realized allocation at all.

Super classes

Design -> DesignFixed -> DesignFixedBernoulli

Methods

Public methods

• DesignFixedBernoulli$is_a_bernoulli_capable()

• DesignFixedBernoulli$new()

• DesignFixedBernoulli$clone()

DesignFixedBernoulli$is_a_bernoulli_capable()

Characterization: this design draws each subject's treatment assignment as an independent $\mathrm{Bernoulli}(p)$ coin flip (see class documentation), so it is Bernoulli-capable by construction.

Usage

DesignFixedBernoulli$is_a_bernoulli_capable()

Returns

Always TRUE for this class.

DesignFixedBernoulli$new()

Initialize a fixed Bernoulli (independent-coin-flip) experimental design. Unlike DesignFixediBCRD, the realized number of treated subjects is not fixed at n * prob_T; it is random ($\mathrm{Binomial}(n, prob\_T)$) because each subject's assignment is an independent coin flip (see class documentation).

Usage

DesignFixedBernoulli$new(
  response_type,
  prob_T = 0.5,
  include_is_missing_as_a_new_feature = TRUE,
  n = NULL,
  verbose = FALSE,
  missingness_method = "impute",
  design_formula = ~.,
  seed = NULL
)

Arguments

Returns

A new 'DesignFixedBernoulli' object

DesignFixedBernoulli$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedBernoulli$clone(deep = FALSE)

Arguments

References

Neyman, J. (1923, transl. 1990). "On the Application of Probability Theory to Agricultural Experiments." Statistical Science, 5(4), 465-472, for the potential-outcomes framework under which Bernoulli and complete randomization are compared; see also randomized experiment for orientation on Bernoulli vs. complete (restricted) randomization.

Examples

des = DesignFixedBernoulli$new(n = 10, response_type = 'continuous')
des$add_all_subjects_to_experiment(data.frame(x1 = rnorm(10)))
des$assign_w_to_all_subjects()

Description

A fixed-sample-size DesignFixed that (1) partitions the $n$ subjects into $n/2$ disjoint matched pairs by solving a non-bipartite (optimal) pairwise-matching problem on a covariate distance matrix, minimizing the total within-pair distance across all pairs, then (2) randomizes treatment within each pair independently: for pair $k$, one of its two members is assigned to treatment and the other to control with probability $1/2$ each, independently across pairs. This is the classical matched-pair randomized design (a special case of blocking with block size 2), which guarantees exact covariate balance within every pair (up to the matching algorithm's distance metric) while preserving randomization-based inference validity, in contrast to DesignFixedGreedyDOptimal, which balance the covariates in aggregate via an optimality criterion but do not guarantee pairwise closeness of any two subjects.

Matching algorithm. Pairing is computed once (lazily, on first call to draw_ws_raw()/assign_w_to_all_subjects(), via private$ensure_matching_structure_computed()) by compute_binary_match_structure(), which forms an $n \times n$ pairwise distance matrix — squared Mahalanobis distance if mahal_match = TRUE (the default; using the sample covariance of the covariates, ridge-regularized if singular), or squared Euclidean distance otherwise — and solves the minimum-weight non-bipartite perfect matching on that distance matrix via nonbimatch (nbpMatching, a Suggests-only dependency; loading is deferred until matching is actually needed, so pre-computed w vectors injected via m never require it). For a single covariate ($p = 1$), pairing instead reduces to simply sorting subjects by that covariate and pairing consecutive subjects, since the non-bipartite matching problem is trivial in one dimension. The resulting pairing is cached in private$bms/private$m for the lifetime of the design object (or until explicitly reset via set_m()) and is not recomputed per draw.

Within-pair randomization. Given the fixed pairing, each replicate allocation (see draw_binary_match_assignments_cpp()) independently flips, for every pair, which of its two members is treated (an independent fair coin flip per pair per replicate, using a splitmix64-seeded Mersenne Twister per replicate column for reproducible parallel draws); this guarantees exactly $n/2$ treated subjects overall (only prob_T = 0.5 is supported; the constructor errors otherwise). Passing a pre-computed m to the constructor supplies the matched-pair structure directly (each pair ID occurring in exactly 2 rows), bypassing the matching computation entirely while keeping the same within-pair randomization.

No-covariate fallback. If no covariates are available at draw time (private$m is NULL, e.g. matching hasn't run and no explicit m was supplied), draw_ws_raw() falls back to an unmatched balanced complete randomization (a uniformly random permutation of $n/2$ ones and $n/2$ zeros), since there is no covariate information to match on.

Batch pregeneration. draw_binary_match_assignments_cpp()'s output is trusted unvalidated – it guarantees exactly n x r valid $\{0,1\}$ columns with $n/2$ treated subjects per column by construction (see fix_design_hierarchy.md, "AllocationMatrixValidation"). supports_batch_w_pregeneration() returns TRUE so that the calling framework generates all replicate w vectors for a simulation cell in one batch (amortizing the one-time nbpMatching matching cost across all replicates of that cell) rather than recomputing the matching structure per replicate.

Super classes

Design -> DesignFixed -> DesignFixedBinaryMatch

Methods

Public methods

• DesignFixedBinaryMatch$is_a_kk_matching_capable()

• DesignFixedBinaryMatch$supports_batch_w_pregeneration()

• DesignFixedBinaryMatch$new()

• DesignFixedBinaryMatch$assign_w_to_all_subjects()

• DesignFixedBinaryMatch$clone()

DesignFixedBinaryMatch$is_a_kk_matching_capable()

Characterization: this design computes its matched-pair structure on the fly from covariates (see class documentation), so it is KK matching-capable by construction.

Usage

DesignFixedBinaryMatch$is_a_kk_matching_capable()

Returns

Always TRUE for this class.

DesignFixedBinaryMatch$supports_batch_w_pregeneration()

Returns TRUE so the calling framework pre-generates all replicate w vectors for a simulation cell in one batch, paying the one-time nbpMatching non-bipartite matching cost once per cell and reusing the resulting pairing across all replicates, rather than recomputing it per replicate.

Usage

DesignFixedBinaryMatch$supports_batch_w_pregeneration()

Returns

Always TRUE for this class.

DesignFixedBinaryMatch$new()

Initialize a binary (non-bipartite) matched-pair fixed experimental design. Matching itself is deferred until the first draw (see class documentation); this constructor only records configuration and, if m is supplied, installs the explicit pairing immediately.

Usage

DesignFixedBinaryMatch$new(
  response_type,
  prob_T = 0.5,
  mahal_match = TRUE,
  include_is_missing_as_a_new_feature = TRUE,
  n = NULL,
  m = NULL,
  verbose = FALSE,
  missingness_method = "impute",
  design_formula = ~.,
  seed = NULL
)

Arguments

Returns

A new 'DesignFixedBinaryMatch' object

DesignFixedBinaryMatch$assign_w_to_all_subjects()

Assign treatment to all subjects (see DesignFixed$assign_w_to_all_subjects() for the general contract). Before delegating, this override ensures the matched-pair structure is computed (private$ensure_matching_structure_computed()) even when w_precomputed is supplied and draw_ws_according_to_design() is therefore never called — downstream code (e.g. blocked/matched-pair inference) still needs private$m to be populated regardless of how w was obtained.

Usage

DesignFixedBinaryMatch$assign_w_to_all_subjects(w_precomputed = NULL)

Arguments

DesignFixedBinaryMatch$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedBinaryMatch$clone(deep = FALSE)

Arguments

References

Greevy, R., Lu, B., Silber, J. H., and Rosenbaum, P. (2004). "Optimal multivariate matching before randomization." Biostatistics, 5(2), 263-275, doi:10.1093/biostatistics/5.2.263, for optimal non-bipartite matched-pair designs prior to randomization. See also matched pair and Mahalanobis distance for orientation.

Examples

des = DesignFixedBinaryMatch$new(n = 10, response_type = 'continuous')
des$add_all_subjects_to_experiment(data.frame(x1 = rnorm(10)))
des$assign_w_to_all_subjects()

Description

A fixed-sample-size DesignFixed in which the unit of randomization is the cluster, not the individual subject: within each block (stratum, formed from strata_cols), whole clusters (identified by cluster_col) are jointly randomized to treatment or control, so all subjects in the same cluster always receive the same assignment. This is the design used when individual-level randomization is infeasible or invalid (e.g. clusters are classrooms, clinics, or households where within-cluster interference/spillover would violate SUTVA under individual randomization), combined with blocking to improve precision by comparing clusters only to other clusters in the same stratum.

Randomization mechanism. Blocking keys are computed per subject via private$get_strata_keys() (shared with other blocking-structure designs): categorical columns in strata_cols are used as-is, continuous columns are discretized into preferred_num_bins_for_continuous_covariate quantile-based bins, and multiple strata_cols are combined into a single composite block key. Within each resulting block, whole clusters (by cluster_col) are randomized to treatment with probability prob_T via block_and_cluster_ra (randomizr), which performs blocked-and-clustered complete random assignment: within each block, clusters (not subjects) are permuted so that, subject to rounding, the target proportion prob_T of clusters in that block is treated, and every subject in a treated cluster receives $w = 1$. r independent replicate allocation columns are generated via replicate() (one randomizr call per replicate; there is no batch/vectorized draw path for this design, unlike DesignFixedBinaryMatch).

Cluster-aware bootstrap. draw_bootstrap_indices() overrides the default subject-level bootstrap to resample at the cluster level via resample_group_rows_cpp(): with bootstrap_type = "within_blocks" (the default when bootstrap_type is NULL), clusters are resampled with replacement within each block, preserving the block structure; otherwise, whole blocks (strata) are themselves resampled with replacement. This mirrors the standard cluster-robust bootstrap principle that resampling must occur at the level of the randomization unit (clusters), not individual subjects, to yield a valid variance/interval estimate under cluster-correlated outcomes.

Super classes

Design -> DesignFixed -> DesignFixedBlockedCluster

Methods

Public methods

• DesignFixedBlockedCluster$is_a_cluster_capable()

• DesignFixedBlockedCluster$new()

• DesignFixedBlockedCluster$clone()

DesignFixedBlockedCluster$is_a_cluster_capable()

Characterization: this design randomizes whole clusters (see class documentation), so it is cluster-structured by construction.

Usage

DesignFixedBlockedCluster$is_a_cluster_capable()

Returns

Always TRUE for this class.

DesignFixedBlockedCluster$new()

Initialize a blocked and cluster randomized fixed experimental design.

Usage

DesignFixedBlockedCluster$new(
  strata_cols,
  cluster_col,
  response_type,
  prob_T = 0.5,
  include_is_missing_as_a_new_feature = TRUE,
  n = NULL,
  preferred_num_bins_for_continuous_covariate = 2,
  num_bins_for_continuous_covariate = NULL,
  verbose = FALSE,
  missingness_method = "impute",
  design_formula = ~.,
  seed = NULL
)

Arguments

Returns

A new 'DesignFixedBlockedCluster' object

DesignFixedBlockedCluster$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedBlockedCluster$clone(deep = FALSE)

Arguments

References

Middleton, J. A., and Aronow, P. M. (2015). "Unbiased estimation of the average treatment effect in cluster-randomized experiments." Statistics, Politics and Policy, 6(1-2), 39-75, doi:10.1515/spp-2013-0002, for blocked/clustered randomized-assignment inference; see also the randomizr package vignette for the assignment-generation conventions this design relies on, and cluster randomized controlled trial for orientation.

Examples

des = DesignFixedBlockedCluster$new(n = 20, response_type = 'continuous',
  strata_cols = 'x2', cluster_col = 'cl')
X = data.frame(x1 = rnorm(20), x2 = factor(rep(1:2, each = 10)), cl = factor(rep(1:10, each = 2)))
des$add_all_subjects_to_experiment(X)
des$assign_w_to_all_subjects()

Description

A fixed-sample-size DesignFixed that first partitions subjects into blocks (strata) formed from covariates, then randomizes treatment independently within each block at probability prob_T (via block_ra when randomizr is installed, else an internal generate_permutations_blocking_cpp() fallback). Blocking on a covariate removes its between-block variation from the treatment-effect comparison (comparisons are always within-block), improving precision relative to unblocked randomization whenever the blocking covariate(s) are prognostic of the outcome, at the cost of requiring the analysis to account for the blocking structure (e.g. via a block/stratum fixed effect or a CMH-type test). This differs from DesignFixedBlockedCluster, which randomizes whole clusters of subjects together within each block rather than subjects individually.

Block construction. Blocking keys are computed by private$get_strata_keys() (shared across blocking-structure designs): each column in strata_cols contributes a categorical key (continuous columns are discretized into preferred_num_bins_for_continuous_covariate quantile bins), and multiple columns are combined into one composite block key per subject; if strata_cols is NULL, all available covariate columns are used. B_target caps the number of resulting blocks by greedily adding strata_cols in order only while the running block count stays at or below the target (earlier columns take priority); exact_num_blocks = TRUE instead hard-fails if the greedy construction does not land on exactly B_target blocks. equal_block_sizes = TRUE (the default) additionally requires every block to have the same subject count, checked once at construction (via n %% B_target) if n and B_target are both already known, and again once covariates arrive; some downstream inference classes (InferenceIncidCMH, InferenceIncidExtendedRobins) require equal block sizes unconditionally, regardless of this flag. An explicit m (one block ID per subject) bypasses covariate-derived block construction entirely.

Within-block randomization and bootstrap. Within each block, treatment is assigned independently via block_ra's complete random assignment (subject to rounding, prob_T of each block's subjects are treated); the internal C++ fallback (generate_permutations_blocking_cpp()) is used only if randomizr is not installed. draw_bootstrap_indices() resamples within each block by default (bootstrap_type = "within_blocks" or NULL, via stratified_bootstrap_indices_cpp()), or resamples whole blocks with replacement otherwise (via resample_group_rows_cpp()) — mirroring the block structure in the resampling scheme, analogous to the cluster-level bootstrap in DesignFixedBlockedCluster.

Super classes

Design -> DesignFixed -> DesignFixedBlocking

Methods

Public methods

• DesignFixedBlocking$new()

• DesignFixedBlocking$clone()

DesignFixedBlocking$new()

Initialize a fixed stratified-block randomized experimental design. Block construction and validation follow the rules described in the class documentation; see the parameter descriptions below for the greedy B_target/exact_num_blocks/equal_block_sizes contract.

Usage

DesignFixedBlocking$new(
  strata_cols = NULL,
  response_type,
  prob_T = 0.5,
  include_is_missing_as_a_new_feature = TRUE,
  n = NULL,
  preferred_num_bins_for_continuous_covariate = 2,
  B_target = NULL,
  exact_num_blocks = FALSE,
  equal_block_sizes = TRUE,
  m = NULL,
  verbose = FALSE,
  missingness_method = "impute",
  design_formula = ~.,
  seed = NULL
)

Arguments

Returns

A new 'DesignFixedBlocking' object

DesignFixedBlocking$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedBlocking$clone(deep = FALSE)

Arguments

References

Fisher, R. A. (1935). The Design of Experiments. Oliver and Boyd, for the original rationale for blocking in randomized experiments; Cochran, W. G., and Cox, G. M. (1957). Experimental Designs (2nd ed.), Wiley, for stratified (randomized block) design theory. See also randomized block design for orientation.

Examples

des = DesignFixedBlocking$new(n = 20, response_type = 'continuous',
  strata_cols = 'x2', equal_block_sizes = FALSE)
X = data.frame(x1 = rnorm(20), x2 = factor(rep(1:2, 10)))
des$add_all_subjects_to_experiment(X)
des$assign_w_to_all_subjects()

Description

A fixed-sample-size DesignFixed in which whole clusters of subjects (identified by cluster_col), rather than individual subjects, are the unit of randomization: every subject in a given cluster always receives the same treatment assignment. This is the unblocked analog of DesignFixedBlockedCluster — there is no stratification step here, so clusters are randomized to treatment as a single pool rather than within strata. Cluster-level randomization is required whenever individual-level randomization would create within-cluster interference/spillover that violates SUTVA (e.g. clusters are classrooms, clinics, villages, or households), at the cost of an effective sample size driven by the number of clusters, not subjects, and a corresponding need for cluster-aware inference.

Randomization mechanism. draw_ws_raw(r) extracts each subject's cluster ID from cluster_col (erroring if any are missing) and calls cluster_ra (randomizr) once per replicate, which performs complete random assignment at the cluster level: subject to rounding, prob_T of clusters are assigned to treatment, and all subjects sharing a cluster inherit that cluster's assignment. r independent replicate columns are generated via replicate() (one randomizr call per replicate).

Cluster-aware bootstrap. draw_bootstrap_indices() overrides the default subject-level bootstrap to resample whole clusters with replacement (via resample_group_rows_cpp()) rather than individual rows, since outcomes are correlated within a cluster (shared assignment plus, typically, shared context) and the exchangeable resampling unit for a valid bootstrap variance/interval estimate is therefore the cluster, not the subject.

Super classes

Design -> DesignFixed -> DesignFixedCluster

Methods

Public methods

• DesignFixedCluster$is_a_cluster_capable()

• DesignFixedCluster$new()

• DesignFixedCluster$clone()

DesignFixedCluster$is_a_cluster_capable()

Characterization: this design randomizes whole clusters (see class documentation), so it is cluster-structured by construction.

Usage

DesignFixedCluster$is_a_cluster_capable()

Returns

Always TRUE for this class.

DesignFixedCluster$new()

Initialize a cluster randomized fixed experimental design (no blocking/stratification; see DesignFixedBlockedCluster if stratification is also needed).

Usage

DesignFixedCluster$new(
  cluster_col,
  response_type,
  prob_T = 0.5,
  include_is_missing_as_a_new_feature = TRUE,
  n = NULL,
  verbose = FALSE,
  missingness_method = "impute",
  design_formula = ~.,
  seed = NULL
)

Arguments

Returns

A new 'DesignFixedCluster' object

DesignFixedCluster$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedCluster$clone(deep = FALSE)

Arguments

References

Middleton, J. A., and Aronow, P. M. (2015). "Unbiased estimation of the average treatment effect in cluster-randomized experiments." Statistics, Politics and Policy, 6(1-2), 39-75, doi:10.1515/spp-2013-0002. See also cluster randomized controlled trial for orientation, and DesignFixedBlockedCluster for the blocked variant of this design.

Examples

des = DesignFixedCluster$new(n = 20, response_type = 'continuous', cluster_col = 'cl')
X = data.frame(x = rnorm(20), cl = factor(rep(1:5, each = 4)))
des$add_all_subjects_to_experiment(X)
des$assign_w_to_all_subjects()

Description

A fixed-sample-size DesignFixed for factorial treatment structures: subjects are assigned to one of the cells of a factorial combination of one or more named factors (e.g. list(treatment = 2), or, once multi-arm support lands, list(drug = 2, dose = 2) for a $2 \times 2$ design), with assignment counts balanced as evenly as possible across cells within each replicate draw.

Currently restricted to exactly two total factor-level combinations (i.e. two arms), e.g. a single two-level factor — the product of levels across all factors entries must equal exactly 2; the constructor errors otherwise. In this two-arm regime, the design reduces to a balanced complete randomization between cell 1 ($w = 0$) and cell 2 ($w = 1$), and w follows the same {0,1} internal / {-1,+1} public convention as every other Design subclass, so DesignFixedFactorial inherits assign_w_to_all_subjects(), draw_ws_according_to_design(), and get_w() unmodified from DesignFixed/Design and works unmodified with every Inference class; only draw_ws_raw() (the low-level allocation-vector generator) and get_w_factorial() (an additional factor-level accessor, see below) are specific to this class. Support for more than two combinations (true multi-factor, multi-arm designs) is tracked separately — see package_metadata/new_feature_plans/multi_arm_designs.md.

Allocation generation. draw_ws_raw(r) builds a base allocation vector by repeating the sequence of cell indices 0:(num_combinations - 1) out to length $n$ (so cells are as close to equally represented as possible, off by at most one subject when $n$ is not a multiple of the number of cells), then independently permutes ( sample) that base vector once per replicate column to produce r balanced-but-randomized allocations.

Super classes

Design -> DesignFixed -> DesignFixedFactorial

Methods

Public methods

• DesignFixedFactorial$new()

• DesignFixedFactorial$get_w_factorial()

• DesignFixedFactorial$clone()

DesignFixedFactorial$new()

Initialize a factorial fixed experimental design. The product of levels implied by factors must currently equal exactly 2 (see class documentation); any other total raises an error.

Usage

DesignFixedFactorial$new(
  factors,
  response_type,
  include_is_missing_as_a_new_feature = TRUE,
  n = NULL,
  verbose = FALSE,
  missingness_method = "impute",
  design_formula = ~.,
  seed = NULL
)

Arguments

Returns

A new 'DesignFixedFactorial' object

DesignFixedFactorial$get_w_factorial()

Decode each subject's scalar cell index (private$w, in 0:(num_combinations - 1)) back into its per-factor level assignments, using the same expand.grid enumeration (private$combinations) established at construction. This is the inverse of the encoding draw_ws_raw() produces, and is the only way to recover individual factor levels once support for more than two total combinations lands, since get_w() (inherited, see class documentation) only ever returns the scalar 0/1 (or -1/+1) cell index.

Usage

DesignFixedFactorial$get_w_factorial()

Returns

A data frame with n rows and one column per entry of factors, giving each subject's level (an integer in 1:levels) for that factor; NULL if treatment has not yet been assigned to all subjects (i.e. private$w is empty or contains NA).

DesignFixedFactorial$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedFactorial$clone(deep = FALSE)

Arguments

Examples

des = DesignFixedFactorial$new(n = 12, response_type = 'continuous', factors = list(treatment = 2))
des$add_all_subjects_to_experiment(data.frame(x=1:12))
des$assign_w_to_all_subjects()

Description

A fixed-sample-size DesignFixed that searches, among balanced ($n/2$-treated) allocations, for one that directly minimizes a covariate imbalance criterion $f(d)$, $d = M(2w - 1)$, via a native C++ (RcppEigen + OpenMP) greedy pairwise-swap search (greedy_design_search_cpp()). Unlike DesignFixedGreedyDOptimal, which optimizes a model-based information-matrix criterion (D-/A-optimality) implied by an assumed linear model, this design optimizes a direct covariate-distance criterion between the treated and control group means/covariance, with no linear-model assumption: the two supported objectives are

• "mahal_dist" (default): $d = L^{-1} X^\top (2w-1) / n$ where $\Sigma = LL^\top$ is the Cholesky factor of the covariate covariance matrix, and $f(d) = \lVert d \rVert_2^2$ — the squared Mahalanobis distance between the treated and control covariate means, accounting for covariate correlation/scale. Falls back to "abs_sum_diff" if the covariate covariance matrix is (numerically) singular, since the Cholesky factorization then fails.

• "abs_sum_diff": $d = X_{\mathrm{std}}^\top (2w-1) / n$ (covariates standardized to unit variance, no correlation adjustment) and $f(d) = \lVert d \rVert_1$ — the sum of absolute standardized mean differences across covariates.

Search algorithm. Starting from a random balanced (Fisher-Yates) allocation, the search runs in one of two modes selected by n_iter: Inf (default) runs exhaustive best-improvement search — each round scans every (treated, control) pair, applies the single globally best improving swap, and repeats until no swap improves $f(d)$, guaranteeing convergence to a strict local optimum; a positive integer instead runs exactly that many stochastic steps, each picking a uniformly random (treated, control) pair and accepting the swap only if it improves $f(d)$ (with patience-based early stopping). r independent design searches (one per requested replicate) run in parallel via OpenMP, each with its own std::mt19937 generator. This search's randomization is reproducible via the constructor's seed argument: per-thread RNGs are seeded from R's own RNG state (GetRNGstate()/unif_rand()) before the parallel region begins, so private$maybe_set_seed() does govern the resulting allocation, independent of the number of OpenMP threads used.

Constraints and fallbacks. Only exactly balanced allocation (prob_T = 0.5, $n$ even) is supported; the constructor errors otherwise. If no covariates are available, the search degenerates to pure balanced Fisher-Yates randomization (no swap search, since there is nothing to balance on). greedy_design_search_cpp()'s output is trusted unvalidated – it guarantees exactly n x r valid $\{0,1\}$ columns with $n/2$ treated subjects per column by construction (see fix_design_hierarchy.md, "AllocationMatrixValidation").

Super classes

Design -> DesignFixed -> DesignFixedGreedy

Methods

Public methods

• DesignFixedGreedy$new()

• DesignFixedGreedy$supports_batch_w_pregeneration()

• DesignFixedGreedy$clone()

DesignFixedGreedy$new()

Initialize a greedy pairwise-swap search fixed experimental design. Only prob_T = 0.5 is supported (see class documentation).

Usage

DesignFixedGreedy$new(
  response_type,
  prob_T = 0.5,
  objective = "mahal_dist",
  n_iter = Inf,
  include_is_missing_as_a_new_feature = TRUE,
  n = NULL,
  verbose = FALSE,
  missingness_method = "impute",
  design_formula = ~.,
  seed = NULL
)

Arguments

Returns

A new 'DesignFixedGreedy' object

DesignFixedGreedy$supports_batch_w_pregeneration()

Returns TRUE so the calling framework pre-generates all replicate w vectors for a simulation cell in a single batched call to greedy_design_search_cpp() (which parallelizes the r independent searches over OpenMP threads internally), rather than issuing r separate single-replicate C++ calls.

Usage

DesignFixedGreedy$supports_batch_w_pregeneration()

Returns

Always TRUE for this class.

DesignFixedGreedy$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedGreedy$clone(deep = FALSE)

Arguments

References

Krieger, A. M., Azriel, D., and Kapelner, A. (2019). "Nearly random designs with greatly improved balance." Biometrika, 106(3), 695-701, doi:10.1093/biomet/asz026, for the greedy-swap balance-optimization approach this class implements. See also Mahalanobis distance for orientation on the default objective.

Examples

des = DesignFixedGreedy$new(n = 10, response_type = 'continuous')

Description

A fixed-sample-size DesignFixed that searches, among allocations with exactly $n_T = \mathrm{round}(n \cdot \mathrm{prob}_T)$ treated subjects, for allocations optimizing a model-based information-matrix criterion implied by the linear model $y = \beta_T w + Z_0 \gamma + \epsilon$ with $Z_0 = [1\ X]$, via a native C++ greedy pairwise-exchange (Fedorov/ DETMAX-style) local search. This class is the merger of the former DesignFixedDOptimal and DesignFixedAOptimal classes; the criterion is selected by the objective and interest constructor arguments.

The optimality-criterion family and its argument mapping. Write $M(w) = [w\ Z_0]^\top [w\ Z_0]$ for the information (moment) matrix, $P = Z_0 (Z_0^\top Z_0)^{-1} Z_0^\top$, and $s(w) = n_T - w^\top P w$ (the treatment-coefficient information given the covariate block). The classical criteria map to constructor arguments as follows:

$D_M$ – full-matrix determinant optimality (maximize $\det M(w)$, i.e. $|M|$)

objective = "D", interest = "all". By the Schur-complement identity $\det M(w) = \det(Z_0^\top Z_0) \cdot s(w)$ (with $w^\top w = n_T$ fixed and $Z_0$ not depending on $w$), the covariate block factors out, so $D_M$ reduces to maximizing $s(w)$.

$D_s$ – subset determinant optimality (minimize $\det(K^\top M(w)^{-1} K)$ for a coordinate-selection $K$: the treatment coefficient plus a chosen covariate subset)

the default objective = "D", interest = "treatment" is $D_s$ with the interest set = {treatment}; interest = ~ x1 + x2 (a one-sided formula) or interest = c("x1", "x2") (model-matrix column names) selects treatment + those covariates. Because $w$ enters only the treatment row/column of $M(w)$, every such $D_s$ criterion factorizes as $\det(V_{SS})/s(w)$ with $\det(V_{SS})$ constant in $w$ – so all determinant-type settings ($D_M$ and every $D_s$) select identical allocations and share the same search kernel. For the single treatment contrast, $D_s$-, c-, and per-parameter A-optimality coincide as well, which is why objective = "A", interest = "treatment" is silently equivalent to the default (allowed by design; no message is emitted).

$D_A$ – general contrast optimality (minimize $\det(A^\top M(w)^{-1} A)$ for an arbitrary contrast matrix $A$)

interest = <contrast matrix> – arrives with Stage 2 of the merge plan (the generalized-criterion kernel) and currently raises an informative error, as do interest sets excluding the treatment coefficient.

$D_B$ (and $A_B$) – Bayesian optimality (criteria computed on the posterior information $M(w) + R$)

prior_precision = a scalar $\tau$ or a matrix $R_0$, combined with either objective; see the Bayesian section below for exactly which coefficients a scalar $\tau$ penalizes.

A – trace optimality (minimize $\mathrm{tr}(K^\top M(w)^{-1} K)$)

objective = "A" with interest = "all" (all parameters: objective $(w^\top H w + 1)/s(w)$, $H = Z_0 (Z_0^\top Z_0)^{-2} Z_0^\top$), or with interest = formula/names ($A_s$: same kernel with the subset-restricted $H_S$; see below). Unlike the determinant family, trace criteria over different interest sets generally select different allocations.

Bayesian variants. Supplying prior_precision replaces $(Z_0^\top Z_0)^{-1}$ with the ridge-regularized $(Z_0^\top Z_0 + R_0)^{-1}$ in the construction of $P$ (and $H$), yielding Bayesian D$_B$/A$_B$-optimality. A scalar $\tau$ penalizes the covariate coefficients only – the treatment coefficient and the intercept are unpenalized ($R_0 = \tau \cdot \mathrm{diag}(0, 1, \ldots, 1)$ over $Z_0$'s columns) – and, when standardize_covariates = TRUE (the default), the covariates are centered and scaled to unit variance first so $\tau$ is interpretable per standardized coefficient. A full matrix prior_precision is used as $R_0$ verbatim (dimensions $(1+p) \times (1+p)$ over $[\mathrm{intercept}, \mathrm{covariates}]$ of the design's model matrix; standardize_covariates is ignored).

Search algorithm. For each of the r requested allocations independently: start from a uniformly random balanced-count allocation (a BCRD draw with exactly $n_T$ treated), then repeatedly apply the single best improving treated/control pairwise exchange until no exchange improves the criterion (a strict local optimum). The returned allocations therefore form a restricted-randomization distribution over locally optimal allocations, which is what makes randomization inference possible for this design. The search is reproducible via the constructor's seed argument: the C++ kernels seed a local generator from R's own RNG stream, so a fixed seed yields identical draws (this corrects the former classes' documentation, which predated the RNG migration).

Covariate-subset criteria (D_s/A_s) via interest = a formula or names. interest also accepts a one-sided formula (e.g. ~ x1 + x2) or a character vector of model-matrix column names, meaning the treatment coefficient plus the named covariate coefficients (the treatment is always in the interest set; the intercept never is). Both reduce to the existing kernels with no new machinery: under objective = "D", because $w$ only enters the treatment row/column of $M(w)$, the subset determinant factorizes as $\det(K^\top M(w)^{-1} K) = \det(V_{SS}) / s(w)$ with $\det(V_{SS})$ constant in $w$ – so subset-D selects allocations identical to the default treatment-focused criterion (allowed silently, like objective = "A", interest = "treatment"); under objective = "A", the subset trace criterion is $(w^\top H_S w + 1) / s(w)$ with $H_S = (Z_0 V S)(Z_0 V S)^\top$ built from the selected columns – the same trace kernel with a subset-restricted $H$. Formula terms are expanded against the design's model matrix, so factor covariates must be referred to by their expanded model-matrix column names. Note that restricting the design's model matrix itself via design_formula also changes the default covariate set downstream inference adjusts for (Inference$initialize() inherits the design's formula), whereas interest affects the allocation criterion only. General contrast matrices (D_A), and interest sets excluding the treatment coefficient, arrive with Stage 2 of the merge plan (the generalized-criterion kernel; see package_metadata/finished_features/fix_design_hierarchy.md).

Constraints and fallbacks. prob_T may be any value in $(0, 1)$ for which $1 \le \mathrm{round}(n \cdot \mathrm{prob}_T) \le n - 1$. If no covariates are available, the search degenerates to pure random allocation with $n_T$ treated (there is no criterion to optimize).

Super classes

Design -> DesignFixed -> DesignFixedGreedyDOptimal

Methods

Public methods

• DesignFixedGreedyDOptimal$new()

• DesignFixedGreedyDOptimal$get_objective()

• DesignFixedGreedyDOptimal$get_interest()

• DesignFixedGreedyDOptimal$get_prior_precision()

• DesignFixedGreedyDOptimal$clone()

DesignFixedGreedyDOptimal$new()

Initialize a model-based optimal-search fixed experimental design. Covariates, if any, are supplied later via add_all_subjects_to_experiment(); the optimality search itself does not run until assign_w_to_all_subjects() (or draw_ws_according_to_design()) is called.

Usage

DesignFixedGreedyDOptimal$new(
  response_type,
  prob_T = 0.5,
  objective = "D",
  interest = "treatment",
  prior_precision = NULL,
  standardize_covariates = TRUE,
  n_iter = Inf,
  include_is_missing_as_a_new_feature = TRUE,
  n = NULL,
  verbose = FALSE,
  missingness_method = "impute",
  design_formula = ~.,
  seed = NULL
)

Arguments

Returns

A new 'DesignFixedGreedyDOptimal' object

DesignFixedGreedyDOptimal$get_objective()

The optimality criterion this design was constructed with.

Usage

DesignFixedGreedyDOptimal$get_objective()

Returns

"D" or "A".

DesignFixedGreedyDOptimal$get_interest()

The parameter-interest setting this design was constructed with.

Usage

DesignFixedGreedyDOptimal$get_interest()

Returns

"treatment" or "all".

DesignFixedGreedyDOptimal$get_prior_precision()

The Bayesian prior precision this design was constructed with.

Usage

DesignFixedGreedyDOptimal$get_prior_precision()

Returns

NULL, a positive scalar, or a symmetric matrix.

DesignFixedGreedyDOptimal$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedGreedyDOptimal$clone(deep = FALSE)

Arguments

References

Atkinson, A. C., Donev, A. N., and Tobias, R. D. (2007). Optimum Experimental Designs, with SAS. Oxford University Press, for the D-/A-optimality criteria and exchange algorithms for constrained design search. See also optimal design for orientation.

Examples

des = DesignFixedGreedyDOptimal$new(n = 10, response_type = 'continuous')
des$add_all_subjects_to_experiment(data.frame(x1 = rnorm(10)))
des$assign_w_to_all_subjects()

Description

A fixed-sample-size DesignFixed implementing the individually balanced complete randomized design (iBCRD): the number of treated subjects is fixed at exactly $n_T = \mathrm{round}(n \cdot prob\_T)$, and each allocation $w$ with exactly $n_T$ ones is drawn uniformly at random from the $\binom{n}{n_T}$ possible such allocations (via a Fisher-Yates shuffle of a base vector with $n_T$ ones and $n - n_T$ zeros). This is the classical "complete randomization" reference design of randomization inference: unlike DesignFixedBernoulli (independent per-subject coin flips, random $n_T$), $n_T$ is fixed here, which is what makes exact permutation/randomization tests over the $\binom{n}{n_T}$ allocations well-defined; unlike DesignFixedGreedyDOptimal/ DesignFixedGreedy, no covariate information is used to select among those allocations — every one of the $\binom{n}{n_T}$ allocations is equally likely.

Draw mechanism. draw_ws_raw(r) delegates to generate_permutations_ibcrd_cpp(), which builds one base allocation vector ($n_T$ ones followed by $n - n_T$ zeros) and independently shuffles (Fisher-Yates via std::shuffle) a fresh copy of it per replicate column, seeded from R's own RNG stream (so seed does govern reproducibility here, unlike the A-/D-optimal exchange searches). assign_w_to_all_subjects() draws one such allocation (r = 1) and applies it to all subjects.

Single implicit block. The constructor sets private$m to a constant vector of 1s (a single block containing every subject) once n is known, so that shared blocking/matching machinery that expects a block-membership vector treats the whole sample as one block by default.

Super classes

Design -> DesignFixed -> DesignFixediBCRD

Methods

Public methods

• DesignFixediBCRD$new()

• DesignFixediBCRD$clone()

DesignFixediBCRD$new()

Initialize a fixed individually balanced completely randomized experimental design (see class documentation for the exact randomization law).

Usage

DesignFixediBCRD$new(
  response_type,
  prob_T = 0.5,
  include_is_missing_as_a_new_feature = TRUE,
  n = NULL,
  verbose = FALSE,
  missingness_method = "impute",
  design_formula = ~.,
  seed = NULL
)

Arguments

Returns

A new 'DesignFixediBCRD' object

DesignFixediBCRD$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixediBCRD$clone(deep = FALSE)

Arguments

References

Fisher, R. A. (1935). The Design of Experiments. Oliver and Boyd, for complete randomization as the canonical reference design of randomization inference. See also randomized experiment for orientation on complete vs. Bernoulli randomization.

Examples

des = DesignFixediBCRD$new(n = 10, response_type = 'continuous')
des$add_all_subjects_to_experiment(data.frame(x1 = rnorm(10)))
des$assign_w_to_all_subjects()

Description

A fixed-sample-size DesignFixed that combines DesignFixedBinaryMatch's non-bipartite matched-pair structure with DesignFixedGreedy's greedy imbalance-minimization search, restricted so every move respects the pairing: subjects are first paired by covariate closeness (as in DesignFixedBinaryMatch), guaranteeing exactly one treated and one control subject per pair; then, rather than assigning within-pair treatment status by a coin flip, the greedy search (greedy_design_search_cpp(), pair-constrained mode) chooses which member of each pair is treated so as to directly minimize the same aggregate covariate-imbalance objective as DesignFixedGreedy (squared Mahalanobis distance or sum of absolute standardized mean differences between the treated and control group means) across the whole sample, not just within each pair. This targets both close within-pair matches (from the matching step) and low aggregate covariate imbalance (from the greedy refinement) simultaneously — a strictly more constrained search than plain DesignFixedGreedy, since only the $2^{n/2}$ which-member-treated assignments consistent with the fixed pairing are considered, rather than all $\binom{n}{n/2}$ balanced allocations.

Search algorithm. Pairing is computed by compute_binary_match_structure() exactly as in DesignFixedBinaryMatch (Mahalanobis or Euclidean distance per objective), lazily on first draw and cached in private$bms. Given the pairing, each replicate search initializes with a random coin flip per pair (which member starts treated), then in exhaustive mode (n_iter = Inf, default) repeatedly finds and applies the single pair-flip that most decreases the imbalance objective, stopping at a strict local optimum (or runs exactly n_iter random-pair stochastic flip-if-improving steps otherwise, with patience-based early stopping) — the same two search modes as DesignFixedGreedy, but with moves restricted to "flip which side of a given pair is treated" rather than "swap any treated/control pair of subjects." Random initialization and swap selection are seeded from R's own RNG (via greedy_design_search_cpp()'s per-thread seeding), so seed does govern reproducibility here.

Pair-preserving bootstrap. draw_bootstrap_indices() resamples whole matched pairs (via draw_matching_bootstrap_sample_cpp()) rather than individual subjects, since the greedy search only ever flips which member of a pair is treated (never crosses pairs), so $w$ always has exactly one treated subject per pair — the pair, not the subject, is the exchangeable resampling unit.

Constraints. Only prob_T = 0.5 is supported (the constructor errors otherwise), and n must be divisible by 4 (draw_ws_raw() errors otherwise); n/2 matched pairs are formed regardless of parity, but the additional divisible-by-4 requirement is enforced by this class specifically (unlike DesignFixedBinaryMatch, which only requires even n).

Super classes

Design -> DesignFixed -> DesignFixedMatchingGreedyPairSwitching

Methods

Public methods

• DesignFixedMatchingGreedyPairSwitching$new()

• DesignFixedMatchingGreedyPairSwitching$supports_batch_w_pregeneration()

• DesignFixedMatchingGreedyPairSwitching$clone()

DesignFixedMatchingGreedyPairSwitching$new()

Initialize a fixed design that performs binary matching followed by greedy which-member-treated optimization (see class documentation). Only prob_T = 0.5 is supported, and n must be divisible by 4.

Usage

DesignFixedMatchingGreedyPairSwitching$new(
  response_type,
  prob_T = 0.5,
  include_is_missing_as_a_new_feature = TRUE,
  n,
  verbose = FALSE,
  objective = "mahal_dist",
  n_iter = Inf,
  missingness_method = "impute",
  design_formula = ~.,
  seed = NULL
)

Arguments

Returns

A new DesignFixedMatchingGreedyPairSwitching object.

DesignFixedMatchingGreedyPairSwitching$supports_batch_w_pregeneration()

Returns TRUE so the calling framework pre-generates all replicate w vectors for a simulation cell in one batched call to greedy_design_search_cpp(), paying the one-time nbpMatching pairing cost once per cell (cached in private$bms) and reusing it across all replicates and the OpenMP-parallelized greedy searches, rather than recomputing the pairing per replicate.

Usage

DesignFixedMatchingGreedyPairSwitching$supports_batch_w_pregeneration()

Returns

Always TRUE for this class.

DesignFixedMatchingGreedyPairSwitching$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedMatchingGreedyPairSwitching$clone(deep = FALSE)

Arguments

References

Krieger, A. M., Azriel, D., and Kapelner, A. (2019). "Nearly random designs with greatly improved balance." Biometrika, 106(3), 695-701, doi:10.1093/biomet/asz026; Greevy, R., Lu, B., Silber, J. H., and Rosenbaum, P. (2004). "Optimal multivariate matching before randomization." Biostatistics, 5(2), 263-275, doi:10.1093/biostatistics/5.2.263, for the matched-pair design this class refines.

Examples

des = DesignFixedMatchingGreedyPairSwitching$new(n = 10, response_type = 'continuous')

Description

A fixed-sample-size DesignFixed that computes exactly one allocation $w^*$ – the minimizer of a chosen covariate-imbalance or information objective over all allocations with $n_T = \mathrm{round}(n \cdot \mathrm{prob}_T)$ treated subjects – by numerical optimization, rather than drawing from a restricted-randomization distribution the way DesignFixedGreedy/ DesignFixedGreedyDOptimal do.

The objective family and its argument mapping. Write $Z_0 = [1\ X]$, $P = Z_0 (Z_0^\top Z_0)^{-1} Z_0^\top$, and $s(w) = n_T - w^\top P w$. The objectives map to constructor arguments and solved forms as follows:

"D" (determinant / $D_M$, $D_s$) and "A" with interest = "treatment"

maximize $s(w)$, solved as the binary quadratic program $\min_w w^\top P w$ – identical criteria and interest/prior_precision semantics to DesignFixedGreedyDOptimal (the same shared construction machinery is used, so the two classes optimize literally the same matrices).

"A" with interest = "all" or a covariate subset ($A$, $A_s$)

minimize $(w^\top H w + 1)/s(w)$ with the sibling class's $H$/$H_S$, solved exactly via Dinkelbach's algorithm (Dinkelbach 1967) over product-linearized MILP subproblems.

Bayesian $D_B$/$A_B$

prior_precision = a scalar $\tau$ (covariates only; intercept and treatment unpenalized) or a full matrix $R_0$, replacing $(Z_0^\top Z_0)^{-1}$ with the ridge-regularized inverse – identical to the sibling class.

"mahal_dist" / "abs_sum_diff"

DesignFixedGreedy's covariate-imbalance criteria, definitionally identical (column-centered $X$, the same standardization and singular-covariance fallback), translated to exactly solvable forms: the Mahalanobis criterion is the pure quadratic $w^\top Q w$ with $Q = 4 X \Sigma^{-1} X^\top / n^2$, and the absolute-sum criterion is an l1 objective solved by the standard linear MILP.

"custom"

a user-compiled black box under the user_compiled_fns.h calling convention (double f(const Eigen::MatrixXd& X, const Eigen::VectorXd& w), minimized), supplied via custom_objective; always solved by the annealing path (no structure to linearize).

Solvers and certificates. solver = "auto" (default) uses the exact "ompr" MILP path (optimum_certificate = "global", a certified global optimum) wherever tractable – always for "abs_sum_diff" (pure linear MILP); up to solver_args$linearization_max_n (default 20, set by a GLPK benchmark: the product linearization adds $n(n-1)/2$ auxiliaries and branch-and-bound cost climbs steeply past $n \approx 20$) for the quadratic and Dinkelbach criteria – and the native simulated-annealing solver beyond it, or always for "custom". The annealing solver is a formal method, not a heuristic: Metropolis acceptance over treated/control swaps with a configurable cooling schedule, for which Hajek (1988) proves convergence in probability to the global optimum under a slow-enough (logarithmic) schedule; the practical geometric schedule used by default is asymptotically motivated only, so its certificate is always "annealing_converged", never "global". solver = "ompr"/"annealing" force a path. Commercial backends extend the exact range via solver_args$roi_solver; see that parameter's wiring guides.

Inference. There is no usable randomization distribution conditional on the observed data (given $X$ there is exactly one $w^*$ up to the mirror coin), so permutation-style randomization tests/CIs are unavailable (supports_randomization_draw() is FALSE); the bootstrap randomization test IS available (the mechanism – "optimize this dataset" – is replayed on each resampled covariate matrix), as is all model-based and plain-resampling inference.

The mirror coin. At prob_T = 0.5, whenever the mirror $1 - w^*$ is a verified co-optimum (checked numerically by evaluating the objective, never by a symmetry table), a fair seeded coin picks between $w^*$ and its mirror (mirror_coin = TRUE, the default). This restores exact treated/control label symmetry – and estimator unbiasedness – at zero cost to balance. A mirror that evaluates strictly better than the solver's answer raises an error (it would be a solver bug).

Super classes

Design -> DesignFixed -> DesignFixedOptimal

Methods

Public methods

• DesignFixedOptimal$new()

• DesignFixedOptimal$get_objective()

• DesignFixedOptimal$get_interest()

• DesignFixedOptimal$get_prior_precision()

• DesignFixedOptimal$get_solver()

• DesignFixedOptimal$get_mirror_coin()

• DesignFixedOptimal$get_optimization_diagnostics()

• DesignFixedOptimal$supports_randomization_draw()

• DesignFixedOptimal$prepare_for_resampling_replay()

• DesignFixedOptimal$clone()

DesignFixedOptimal$new()

Initialize a deterministic single-allocation optimal fixed experimental design. The optimization itself does not run until assign_w_to_all_subjects() (or draw_ws_according_to_design(r = 1)) is called.

Usage

DesignFixedOptimal$new(
  response_type,
  prob_T = 0.5,
  objective = "D",
  interest = "treatment",
  prior_precision = NULL,
  standardize_covariates = TRUE,
  custom_objective = NULL,
  solver = "auto",
  solver_args = list(),
  mirror_coin = TRUE,
  include_is_missing_as_a_new_feature = TRUE,
  n = NULL,
  verbose = FALSE,
  missingness_method = "impute",
  design_formula = ~.,
  seed = NULL
)

Arguments

Returns

A new 'DesignFixedOptimal' object

DesignFixedOptimal$get_objective()

The objective this design was constructed with.

Usage

DesignFixedOptimal$get_objective()

Returns

One of "D", "A", "mahal_dist", "abs_sum_diff", "custom".

DesignFixedOptimal$get_interest()

The parameter-interest setting ("D"/"A" only).

Usage

DesignFixedOptimal$get_interest()

Returns

The interest construction argument.

DesignFixedOptimal$get_prior_precision()

The Bayesian prior precision this design was constructed with.

Usage

DesignFixedOptimal$get_prior_precision()

Returns

NULL, a positive scalar, or a symmetric matrix.

DesignFixedOptimal$get_solver()

The solver setting this design was constructed with.

Usage

DesignFixedOptimal$get_solver()

Returns

"auto", "ompr", or "annealing".

DesignFixedOptimal$get_mirror_coin()

The mirror-coin setting this design was constructed with.

Usage

DesignFixedOptimal$get_mirror_coin()

Returns

TRUE or FALSE.

DesignFixedOptimal$get_optimization_diagnostics()

Diagnostics cached by the most recent solve: the solver used, optimum_certificate ("global" for exact "ompr" solves, "annealing_converged" otherwise), the achieved objective value, mirror-coin outcome (mirror_feasible/mirror_tied/mirror_flipped), elapsed time, and the solver's own detail fields.

Usage

DesignFixedOptimal$get_optimization_diagnostics()

Returns

A named list, or NULL if no solve has run yet.

DesignFixedOptimal$supports_randomization_draw()

Characterization: FALSE – given the observed data there is exactly one $w^*$ (up to the vacuous 2-atom mirror pair), so there is no randomization distribution to draw from and permutation-style randomization tests/CIs are unavailable. The bootstrap randomization test remains available via supports_resampling_replay() (the deterministic mechanism is replayed on each resample).

Usage

DesignFixedOptimal$supports_randomization_draw()

Returns

Always FALSE for this class.

DesignFixedOptimal$prepare_for_resampling_replay()

BRT replicate-mode switch (called by the bootstrap-randomization-test machinery ahead of each replayed draw; see Design$prepare_for_resampling_replay()). Subsequent solves inherit the observed assignment's ordinary solver and budget, so each replay targets the same allocation mechanism. Set solver_args$brt_solver = "annealing" to opt into the legacy reduced brt_max_iter/brt_n_chains replay profile, or "ompr" to request the MILP path when the objective permits it. Idempotent; the mirror coin still applies per replicate (the BRT replays the coin-inclusive mechanism).

Usage

DesignFixedOptimal$prepare_for_resampling_replay()

Returns

invisible(NULL).

DesignFixedOptimal$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedOptimal$clone(deep = FALSE)

Arguments

References

Dinkelbach, W. (1967). On nonlinear fractional programming. Management Science 13(7):492-498, for the exact A-optimality reduction. Hajek, B. (1988). Cooling schedules for optimal annealing. Mathematics of Operations Research 13(2):311-329, for the annealing solver's formal convergence property. Atkinson, A. C., Donev, A. N., and Tobias, R. D. (2007). Optimum Experimental Designs, with SAS. Oxford University Press, for the D-/A-optimality criteria.

Examples

# objective = "mahal_dist" (the default MILP path) needs a MILP solver --
# ompr + ompr.roi + a ROI plugin (ROI.plugin.glpk by default), all Suggests,
# not installed automatically with EDI. Confirmed 2026-09-25: ungated, this
# example errored outright on R CMD check's --no-suggests leg (and would do
# the same for any real user without the optional MILP-solver stack), not
# just a CI-specific issue.
if (requireNamespace("ompr", quietly = TRUE) &&
    requireNamespace("ompr.roi", quietly = TRUE) &&
    requireNamespace("ROI.plugin.glpk", quietly = TRUE)) {
  des = DesignFixedOptimal$new(n = 14, response_type = 'continuous', objective = "mahal_dist")
  des$add_all_subjects_to_experiment(data.frame(x1 = rnorm(14)))
  des$assign_w_to_all_subjects()
  des$get_optimization_diagnostics()
}


# A custom compiled objective (the user_compiled_fns.h calling convention),
# built with RcppXPtrUtils::cppXPtr() -- here, squared imbalance of the
# centered covariate sums. Compiling it needs a C++ toolchain and takes
# several seconds:
if (requireNamespace("RcppXPtrUtils", quietly = TRUE)) {
  fobj = RcppXPtrUtils::cppXPtr(
    "double f(const Eigen::MatrixXd& X, const Eigen::VectorXd& w) {
      Eigen::RowVectorXd mu = X.colwise().mean();
      Eigen::MatrixXd Xc = X.rowwise() - mu;
      Eigen::VectorXd s = 2.0 * w - Eigen::VectorXd::Ones(X.rows());
      return (Xc.transpose() * s).squaredNorm();
    }", depends = "RcppEigen")
  des2 = DesignFixedOptimal$new(n = 14, response_type = 'continuous',
    objective = "custom", custom_objective = fobj)
  des2$add_all_subjects_to_experiment(data.frame(x1 = rnorm(14)))
  des2$assign_w_to_all_subjects()
}

Description

A fixed-sample-size DesignFixed that first partitions subjects into B approximately equal-sized, covariate-homogeneous blocks by (approximately or exactly) minimizing total within-block pairwise covariate distance $\sum_{k=1}^{B} \sum_{i, j \in \text{block } k, i < j} D(x_i, x_j)$, then randomizes treatment independently within each resulting block at probability prob_T (via block_ra, the same mechanism as DesignFixedBlocking). Unlike DesignFixedBlocking, which forms blocks from user-specified column-wise strata (categorical levels / quantile bins), here blocks are formed directly from a multivariate distance/clustering criterion over all covariates jointly, so this design generalizes matched-pair designs (DesignFixedBinaryMatch) from block size 2 to arbitrary block size $B$. When B is omitted and n is known at initialization, the default is floor(sqrt(n)), truncated below at 1 (the usual heuristic block count for balancing within-block homogeneity against within-block sample size).

Block-formation algorithms. method selects among three block construction strategies with different exactness/scalability trade-offs (see the new() argument documentation for details): "K-way" (default, balanced k-means-style anticlustering via anticlust, fast and empirically close to optimal), "greedy" (nearest-neighbor greedy matching via blockTools, fast even for large $n$), and "ompr" (an exact mixed-integer program solved with GLPK via ompr/ompr.roi, globally optimal but scaling as $O(n^2 B)$ in the number of decision variables — practical only for small $n$). Block membership is computed lazily (on first draw, via get_or_compute_block_ids()) and cached in private$block_ids for reuse across replicates.

Distance specification ("ompr" only). dist selects the pairwise distance $D(x_i, x_j)$ the exact solver minimizes: "euclidean", "sum_abs_diff" (sum of absolute coordinate differences), "mahal" (default, Mahalanobis distance accounting for covariate correlation/scale), or a user-supplied distance function. The "K-way" and "greedy" methods use their own respective packages' built-in distance conventions and do not consult dist.

No-covariate fallback. If the covariate matrix has zero columns, block membership is assigned by simple round-robin (rep(seq_len(B), length.out = n)) rather than by any of the three clustering algorithms, since there is no covariate information to cluster on.

Solver backend (method = "ompr" only). roi_solver selects the MILP backend ompr.roi dispatches to, a closed set c("glpk", "gurobi", "cplex") (default "glpk") – validated against this set, not passed through to ROI::ROI_registered_solvers() unchecked, so a typo or an unsupported solver name fails fast with a clear message rather than an opaque ompr error three layers down. Gurobi and CPLEX are supported because they extend which block-formation problems stay practical, not just which are expressible: GLPK's branch-and-bound is single-threaded with no commercial-grade presolve/cutting-plane machinery, while Gurobi/CPLEX are typically an order of magnitude faster on the same MILP and solve in parallel, meaningfully extending the $n$ for which the exact "ompr" method stays practical. Scope is deliberately closed to these two for now – not because other ROI plugins (CBC, SYMPHONY, ...) wouldn't work mechanically (the dispatch is generic), but because Gurobi and CPLEX are the two most widely used commercial solvers and the only ones worth a maintained step-by-step guide at this point; extending the closed set is a small, low-risk addition later if a real need for a third backend appears, not a reason to leave the set open-ended now.

Wiring up Gurobi:

1. Obtain a Gurobi license (a free academic license is available from Gurobi for non-commercial use) and install the Gurobi Optimizer itself. This sets up GUROBI_HOME and the license file (gurobi.lic, discoverable via the GRB_LICENSE_FILE environment variable or Gurobi's default search path) – entirely outside this package's control or dependency graph.

2. Install Gurobi's own R package. Not available via CRAN – it ships inside the Gurobi installation itself: R CMD INSTALL "$GUROBI_HOME/R/gurobi_<version>_R_<Rmajor.minor>.tar.gz" (exact filename/path depends on your Gurobi version and platform; see the R/ subdirectory of your Gurobi install). This is the vendor interface ROI.plugin.gurobi wraps – required even though it's not what you call directly.

3. Install the ROI bridge package from CRAN: install.packages("ROI.plugin.gurobi"). This package is on CRAN (it only depends on ROI + the gurobi R package from step 2 being present at load time) and is the only new artifact this class's own dependency graph ever touches.

4. Verify: after library(ROI.plugin.gurobi), "gurobi" %in% ROI::ROI_registered_solvers() should be TRUE.

5. Pass roi_solver = "gurobi" to the constructor.

Wiring up CPLEX:

1. Obtain an IBM CPLEX license (a free academic license is available from IBM) and install IBM ILOG CPLEX Optimization Studio.

2. Install Rcplex (CRAN), CPLEX's R interface. Unlike ROI.plugin.gurobi, Rcplex is a source package that compiles against your local CPLEX installation – it needs to be pointed at your CPLEX SDK's include/lib directories at install time (typically via configure.args to install.packages(), naming your CPLEX version's cplex/include/cplex/lib/<platform> paths). The exact flag names and paths are CPLEX-version- and platform-specific – follow Rcplex's own INSTALL/README instructions for your installed CPLEX version rather than a fixed command copied from here, since this changes across CPLEX releases.

3. Install the ROI bridge package from CRAN: install.packages("ROI.plugin.cplex") (depends on Rcplex from step 2 being present and working).

4. Verify: after library(ROI.plugin.cplex), "cplex" %in% ROI::ROI_registered_solvers() should be TRUE.

5. Pass roi_solver = "cplex" to the constructor.

Dependency-graph consequence: ROI.plugin.gurobi/ROI.plugin.cplex (and Rcplex) are never added to Suggests – they're free/CRAN- available themselves, but declaring them would misrepresent the dependency as something install.packages("EDI", dependencies = TRUE) could satisfy, when the vendor package/license underneath cannot be. The lazy-check pattern already used for ompr/ompr.roi/ROI.plugin.glpk extends naturally: check requireNamespace("ROI.plugin.gurobi"/"ROI.plugin.cplex") at solve time (not at package load or class-definition time) for whichever roi_solver was requested, and error informatively – naming the missing package and, if that's present but the solve still fails, noting the likely cause is a missing vendor license/installation, not something this class can diagnose further.

Bootstrap. draw_bootstrap_indices() resamples within blocks by default (bootstrap_type = "within_blocks" or NULL, via stratified_bootstrap_indices_cpp()) or resamples whole blocks otherwise (via resample_group_rows_cpp()), mirroring the block structure in the resampling scheme, as in DesignFixedBlocking.

Super classes

Design -> DesignFixed -> DesignFixedOptimalBlocks

Methods

Public methods

• DesignFixedOptimalBlocks$supports_batch_w_pregeneration()

• DesignFixedOptimalBlocks$new()

• DesignFixedOptimalBlocks$clone()