Package {EDI}

Type:	Package
Title:	Experimental Design and Inference
Version:	1.0.2
Description:	Implements a comprehensive suite of experimental designs, both fixed (e.g., block, stratified, matched-pair, cluster, factorial, and mixed-integer-programming-based optimal designs) and sequential (including matching-on-the-fly designs, biased coin designs, and covariate-adaptive urn designs that assign treatment one subject at a time while maintaining covariate balance), for continuous, incidence, count, proportion, survival, and ordinal response types. For each design and response type combination, provides the corresponding inference procedures, including exact, asymptotic, distribution-free, and resampling-based (bootstrap, jackknife, and randomization) methods, so that estimation and testing are always matched to how the data were generated. An 'InferenceSuite' facility runs all applicable inference procedures for a given design and response type at once and reports a single Cauchy-combined p-value summarizing their evidence. A built-in simulation framework supports power analysis and operating-characteristic studies across designs, response types, and inference procedures, with optional parallelization via 'mirai'. Missing covariate data is handled automatically via built-in imputation. Core numerical routines are implemented in C++ via 'Rcpp' for speed on large designs and simulation studies. Machine-specific tuning for optimization is included.
License:	GPL-3
Encoding:	UTF-8
Language:	en-US
Depends:	R (≥ 3.5.0)
LinkingTo:	Rcpp, RcppEigen, RcppNumerical
Imports:	R6, checkmate, Rcpp, data.table, survival, missRanger, missForest, numDeriv, digest, methods, MASS, RhpcBLASctl, randomizr
Suggests:	anticlust, blockTools, clinfun, coin, dplyr, mirai, aftgee, betareg, copula, doParallel, ggplot2, fixest, gamlss.dist, geepack, glmmTMB, glmnet, icenReg, interval, jsonlite, knitr, lme4, multgee, nbpMatching, nlme, nnet, ordinal, pscl, qpdf, quantreg, R.utils, RcppXPtrUtils, Rfit, rmarkdown, testthat, VGAM, ompr, ompr.roi, ROI.plugin.glpk, sandwich, withr
VignetteBuilder:	knitr
Collate:	'design_abstract.R' 'design_blocking_abstract.R' 'design_matching_abstract.R' 'design_fixed_abstract.R' 'design_component_registry.R' 'design_class_factory.R' 'design_fixed_greedy.R' 'helper_optimal_shared.R' 'helper_optimal_milp_solvers.R' 'helper_user_compiled_fn.R' 'helper_optimal_annealing.R' 'design_fixed_greedy_d_optimal.R' 'design_fixed_bernoulli.R' 'design_fixed_binary_match.R' 'design_fixed_blocked_cluster.R' 'design_fixed_blocking.R' 'design_fixed_cluster.R' 'design_fixed_factorial.R' 'design_fixed_ibcrd.R' 'design_fixed_matching_greedy_pair_switching.R' 'design_fixed_optimal.R' 'design_fixed_optimal_blocks.R' 'design_fixed_rerandomization.R' 'design_observational.R' 'design_observational_blocks.R' 'design_observational_matching.R' 'design_seq_one_by_one_abstract.R' 'design_custom_extensions.R' 'design_seq_one_by_one_atkinson.R' 'design_seq_one_by_one_bernoulli.R' 'design_seq_one_by_one_efron.R' 'design_seq_one_by_one_ibcrd.R' 'design_seq_one_by_one_KK14.R' 'design_seq_one_by_one_KK21_stepwise.R' 'design_seq_one_by_one_KK21.R' 'design_seq_one_by_one_pocock_simon.R' 'design_seq_one_by_one_random_block_size.R' 'design_seq_one_by_one_spbr.R' 'design_seq_one_by_one_urn.R' 'design_class_registry.R' 'EDI.R' 'helper_glm_fit.R' 'globals.R' 'comprehensive_slow_paths.R' 'helper_additional_asserts.R' 'contracts_mixins.R' 'helper_robust_sandwich.R' 'inference_all_abstract_mle_or_KM_summary_table.R' 'inference_ext_ci_inversion.R' 'inference_ext_information_matrix.R' 'inference_ext_likelihood_test_memoization.R' 'inference_mixin_off_optimum_likelihood_eval.R' 'inference_all_abstract_asymp_lik.R' 'inference_all_abstract_marginal_estimand.R' 'inference_ext_bartlett_approx.R' 'inference_mixin_cordeiro_ferrari_approx.R' 'inference_mixin_lemonte_gradient_approx.R' 'inference_mixin_kk_gee_shared.R' 'inference_mixin_kk_glmm_shared.R' 'inference_mixin_kk_passthrough.R' 'inference_mixin_kk_passthrough_compound.R' 'helper_bootstrap_ci.R' 'contracts_resampling_draws.R' 'inference_ext_bca_bootstrap_ci.R' 'inference_ext_exchangeable_resampling_units.R' 'inference_ext_minimum_volatility_selector.R' 'inference_ext_m_out_of_n_bootstrap.R' 'inference_ext_prw_subsampling.R' 'inference_all_abstract_non_param_boot.R' 'inference_all_abstract_rand_bootstrap.R' 'inference_all_abstract_rand_bootstrap_ci.R' 'inference_all_abstract_bayesian_bootstrap.R' 'inference_all_abstract_jackknife.R' 'inference_all_abstract_exact.R' 'inference_all_abstract_asymp.R' 'inference_ext_param_bootstrap_estimate.R' 'inference_all_abstract_param_boot.R' 'inference_all_abstract_asymp_lik_std_mod_cache.R' 'inference_all_abstract_count_likelihood.R' 'inference_ext_quantile_rand_ci.R' 'inference_all_abstract_rand_ci.R' 'inference_ext_sequential_mc_pval.R' 'inference_all_abstract_rand.R' 'inference_all_abstract.R' 'inference_all_abstract_KK_passthrough_compound.R' 'inference_all_abstract_quantile_rand_ci.R' 'inference_all_KK_mean_diff_IVWC.R' 'inference_all_KK_quantile_regr_ivwc_abstract.R' 'inference_all_KK_quantile_regr_one_lik_abstract.R' 'inference_all_KK_wilcox_ivwc.R' 'inference_all_average_diff.R' 'inference_all_simple_mean_diff_pooled_var.R' 'inference_all_simple_wilcox.R' 'inference_continuous_KK_bai_abstract.R' 'inference_continuous_KK_glmm.R' 'inference_continuous_KK_ols_ivwc.R' 'inference_continuous_KK_ols_one_lik.R' 'inference_continuous_KK_quantile_regr_ivwc.R' 'inference_continuous_KK_quantile_regr_one_lik.R' 'inference_continuous_KK_robust_regr_ivwc.R' 'inference_continuous_KK_robust_regr_one_lik.R' 'inference_continuous_KK14_bai.R' 'inference_continuous_KK21_bai.R' 'inference_continuous_lin.R' 'inference_continuous_ols.R' 'inference_continuous_quantile_regr.R' 'inference_continuous_robust_regr.R' 'inference_count_composite_likelihood.R' 'inference_count_KK_combined.R' 'inference_count_KK_cond_poisson.R' 'inference_count_KK_gee.R' 'inference_count_negbin.R' 'inference_count_poisson.R' 'inference_count_quasipoisson.R' 'inference_count_robust_poisson.R' 'inference_count_zero_augmented_poisson_abstract.R' 'inference_count_hurdle.R' 'inference_count_zero_inflated.R' 'inference_custom_extensions.R' 'inference_rand_custom.R' 'inference_helpers_zhang.R' 'inference_incidence_binomial_identity.R' 'inference_incidence_cmh.R' 'inference_incidence_exact_binomial.R' 'inference_incidence_exact_zhang.R' 'inference_incidence_extended_robins.R' 'helper_gcomp.R' 'helper_marginal_estimand.R' 'inference_incidence_gcomp_abstract.R' 'inference_incidence_gcomp.R' 'inference_incidence_KK_cond_logit_glmm_abstract.R' 'inference_incidence_KK_cond_logit_glmm.R' 'inference_incidence_KK_cond_logit.R' 'inference_incidence_KK_combined.R' 'inference_incidence_KK_gcomp_abstract.R' 'inference_incidence_KK_marginal_abstract.R' 'inference_incidence_KK_marginal.R' 'inference_incidence_KK_newcombe_ivwc_univ.R' 'inference_incidence_log_binomial.R' 'inference_incidence_logit.R' 'inference_incidence_miettinen_nurminen_univ.R' 'inference_incidence_modified_poisson.R' 'inference_incidence_newcombe_univ.R' 'inference_incidence_probit.R' 'inference_incidence_risk_diff.R' 'inference_incid_wald.R' 'inference_indicidence_exact_fisher.R' 'inference_ordinal_adj_cat_logit.R' 'inference_ordinal_cauchit.R' 'inference_ordinal_cloglog.R' 'inference_ordinal_gcomp.R' 'inference_ordinal_jonckheere_terpstra_test.R' 'inference_ordinal_KK_clmm_abstract.R' 'inference_ordinal_KK_combined.R' 'inference_ordinal_KK_cond_adj_cat_logit.R' 'inference_ordinal_KK_cond_logit_abstract.R' 'inference_ordinal_ordered_probit.R' 'inference_ordinal_paired_sign_test.R' 'inference_ordinal_partial_proportional_odds.R' 'inference_ordinal_proportional_odds.R' 'inference_ordinal_ridit.R' 'inference_ordinal_stereotype_logit.R' 'inference_proportion_beta.R' 'inference_proportion_fractional_logit.R' 'inference_proportion_gcomp.R' 'inference_proportion_KK_combined.R' 'inference_proportion_KK_quantile_regr_ivwc.R' 'inference_proportion_KK_quantile_regr_one_lik.R' 'inference_proportion_quantile_regr.R' 'inference_proportion_zero_one_inflated_beta.R' 'inference_suite.R' 'inference_survival_coxph.R' 'inference_survival_dep_cens_transform.R' 'inference_survival_gehan_wilcox.R' 'inference_survival_GLMM_weibull_frailty_loggamma.R' 'inference_survival_KK_lwa_cox_ivwc_abstract.R' 'inference_survival_KK_lwa_cox_one_lik_abstract.R' 'inference_survival_KK_lwa_cox.R' 'inference_survival_KK_rank_regr_ivwc_abstract.R' 'inference_survival_KK_rank_regr.R' 'inference_survival_KK_strat_cox.R' 'inference_survival_GLMM_weibull_frailty_normal.R' 'inference_survival_KK_weibull_marginal.R' 'inference_survival_km_diff.R' 'inference_survival_log_rank.R' 'inference_survival_rmst.R' 'inference_survival_strat_cox.R' 'inference_survival_weibull.R' 'inference_class_registry.R' 'helper_package_checks.R' 'helper_math.R' 'helper_model_matrix.R' 'helper_response_asserts.R' 'helper_robust_regression.R' 'helper_rcpp_doc_stubs.R' 'helper_matching.R' 'helper_survival_fits.R' 'helper_zoib.R' 'helper_inference_survival_turnbull.R' 'RcppExports.R' 'simulations_framework.R' 'simulation_framework_report.R' 'local_machine_tuning_synthetic_fixtures.R' 'local_machine_tuning_harness.R' 'local_machine_tuning_axes.R' 'local_machine_tuning_persistence.R' 'local_machine_tuning_correctness.R' 'local_machine_tuning.R' 'zzz.R'
URL:	https://github.com/kapelner/EDI, https://kapelner.github.io/EDI/, https://pypi.org/project/edi-kernels/
BugReports:	https://github.com/kapelner/EDI/issues
Config/roxygen2/version:	8.0.0.9000
NeedsCompilation:	yes
Packaged:	2026-09-25 14:50:44 UTC; kapelner
Author:	Adam Kapelner [aut, cre, cph]
Maintainer:	Adam Kapelner <adam.kapelner@mail.huji.ac.il>
Repository:	CRAN
Date/Publication:	2026-10-07 09:00:15 UTC

Experimental Design and Inference

Description

EDI

Details

Provides comprehensive support for many fixed and sequential experimental designs and many infererential methods (parametric, nonparametric, exact) for response types continuous, incidence, count, proportion, survival (with censoring) and ordinal. Supports automatic missing data imputation, parallelization, provides robustness fallbacks and is optimized with C++.

Author(s)

Adam Kapelner kapelner@qc.cuny.edu

References

Adam Kapelner and Abba Krieger A Matching Procedure for Sequential Experiments that Iteratively Learns which Covariates Improve Power, Arxiv 2010.05980

See Also

Useful links:

• https://github.com/kapelner/EDI

• https://kapelner.github.io/EDI/

• https://pypi.org/project/edi-kernels/

• Report bugs at https://github.com/kapelner/EDI/issues

Abstract Quantile Regression Compound Estimator for KK Matching-on-the-Fly Designs

Description

An abstract base class providing shared quantile regression logic for KK matching-on-the-fly designs. Subclasses override the transform_y_fn private$m field to apply a response transformation before quantile regression (e.g., identity for continuous, qlogis for proportion outcomes).

Usage

.init_kk_quantile_regr_ivwc(
  self,
  private,
  super,
  des_obj,
  model_formula,
  tau,
  transform_y_fn,
  verbose,
  smart_cold_start_default
)

Abstract Quantile Regression Combined-Likelihood Compound Estimator for KK Designs

Description

Fits a single joint quantile regression over all KK design data by stacking matched-pair differences and reservoir observations into one design matrix.

Usage

.init_kk_quantile_regr_one_lik(
  self,
  private,
  super,
  des_obj,
  model_formula,
  tau,
  transform_y_fn,
  verbose
)

Details

Column layout of X_stack: [beta_0 | beta_T | beta_xs (p cols)] Pair rows: [0 | 1 | Xd_k] -> Q_tau(yd_k) = beta_T + Xd_k' beta_xs Reservoir rows: [1 | w_i | X_i] -> Q_tau(y_i) = beta_0 + w_i*beta_T + X_i'*beta_xs Fitting a single rq() on the stacked dataset minimises the combined check-function loss.

Special cases: Pairs only: beta_0 column is all-zero and dropped; layout [beta_T | beta_xs]. Reservoir only: standard quantile regression layout [beta_0 | beta_T | beta_xs].

Standard errors use Powell's "nid" sandwich estimator, falling back to "iid".

Normalize and Validate an Optimizer Algorithm Name for the fast_* C++ Backends

Description

Internal helper shared by the package's fast_* GLM/survival/ordinal fitting wrappers (e.g. fast_logistic_regression, fast_coxph_regression) to resolve a user-supplied optimization_alg argument to one of the fixed set of optimizer names the underlying C++ backends actually implement, applying a model-specific default when none is supplied and rejecting anything else. This centralizes the default/validation logic so each fast_* wrapper does not have to repeat it.

Usage

.normalize_optimizer_algorithm(
  optimization_alg,
  allow_irls = FALSE,
  default = if (allow_irls) "irls" else "lbfgs"
)

Arguments

Details

The three possible optimizer names, when supported by a given model, correspond to distinct fitting algorithms in the C++ backends: "newton_raphson" (full Newton-Raphson using the analytic Hessian), "lbfgs" (limited-memory quasi-Newton, avoiding an explicit Hessian), and "irls" (iteratively reweighted least squares, the classical GLM-fitting algorithm — only meaningful, and only offered, for exponential-family GLMs, hence gated by allow_irls). Which optimizers a given fast_* function actually accepts (and which is its default) varies by model; this function only encodes the generic irls-vs-not-irls split, not per-model specifics.

optimization_alg is matched against the allowed set via match.arg, so unambiguous partial string matches (e.g. "newton") are accepted; an unmatched or ambiguous value raises match.arg's standard error rather than silently falling back to the default. missing(optimization_alg) or an explicit NULL both resolve to default before matching.

Value

A validated, unabbreviated character string: one of "newton_raphson", "lbfgs", or (only when allow_irls = TRUE) "irls".

See Also

match.arg, which performs the validation/partial-matching.

Inference based on Maximum Likelihood for KK designs

Description

Initialize Bai adjusted-t inference for a completed KK continuous-response design, including the optional convex combination of matched-pair and reservoir estimates.

Computes the appropriate estimate for compound mean difference across pairs and reservoir

Computes a 1-alpha level frequentist confidence interval

Here we use the theory that MLE's computed for GLM's are asymptotically normal (except in the case of estimat_type "median difference" where a nonparametric bootstrap confidence interval (see the controlTest::quantileControlTest method) is employed. Hence these confidence intervals are asymptotically valid and thus approximate for any sample size.

Compute the Bai-adjusted two-sided p-value for the treatment effect using the matched-design adjusted statistic. See related InferenceBaiAdjustedTKK14 methods.

Usage

BaiAdjustedTSource

Details

Inference for mean difference. Note that warm starts are disabled for this class as the Bai adjusted t-test is a closed-form estimator and does not benefit from initialization.

This class requires the nbpMatching package, which is listed in Suggests and is not installed automatically with EDI. Install it manually with install.packages("nbpMatching") before using this class.

Value

The setting-appropriate (see description) numeric estimate of the treatment effect

A (1 - alpha)-sized frequentist confidence interval for the treatment effect

The approximate frequentist p-value

Examples

# (loading the nbpMatching package alone takes a few seconds)
if (requireNamespace("nbpMatching", quietly = TRUE)) {
  seq_des = DesignSeqOneByOneKK14$new(n = 20, response_type = "continuous")
  for (i in 1:20) {
    seq_des$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1), x2 = rnorm(1)))
  }
  seq_des$add_all_subject_responses(rnorm(20))
  seq_des_inf = InferenceBaiAdjustedTKK14$new(seq_des)
  seq_des_inf$compute_estimate()
}



# (loading the nbpMatching package alone takes a few seconds)
if (requireNamespace("nbpMatching", quietly = TRUE)) {
  seq_des = DesignSeqOneByOneKK14$new(n = 20, response_type = "continuous")
  for (i in 1:20) {
    seq_des$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1), x2 = rnorm(1)))
  }
  seq_des$add_all_subject_responses(rnorm(20))
  seq_des_inf = InferenceBaiAdjustedTKK14$new(seq_des)
  seq_des_inf$compute_asymp_confidence_interval()
}



# (loading the nbpMatching package alone takes a few seconds)
if (requireNamespace("nbpMatching", quietly = TRUE)) {
  seq_des = DesignSeqOneByOneKK14$new(n = 20, response_type = "continuous")
  for (i in 1:20) {
    seq_des$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1), x2 = rnorm(1)))
  }
  seq_des$add_all_subject_responses(rnorm(20))
  seq_des_inf = InferenceBaiAdjustedTKK14$new(seq_des)
  seq_des_inf$compute_asymp_two_sided_pval()
}

Robust-Regression IVWC Compound Inference for KK Designs

Description

Initialize KK inverse-variance combined robust-regression inference and prepare the matched/reservoir components used by InferenceContinKKRobustRegrIVWC.

Point estimate of the treatment effect combining a matched-pair robust regression (MASS::rlm on within-pair differences) and a reservoir robust regression (treatment vs. control), combined by inverse-variance weighting: the two component estimates \hat\beta_{T,\text{matched}} and \hat\beta_{T,\text{reservoir}} (each with its own estimated variance) are combined as \hat\beta_T = \sum_k w_k \hat\beta_{T,k} / \sum_k w_k with w_k = 1/\widehat{\mathrm{Var}}(\hat\beta_{T,k}); a component is dropped from the combination if it is not estimable (e.g. too few observations). See Inference for the general estimate contract.

Wald confidence interval for the inverse-variance-combined treatment effect: \hat\beta_T \pm t_{1-\alpha/2,\,df}\cdot \hat{se}(\hat\beta_T), using the combined variance 1/\sum_k w_k from compute_estimate()'s inverse-variance weighting. likelihood_tier = "quasi" for this class (M/MM-estimator objective, not a normalized likelihood), so only the Wald testing type is supported. See InferenceAsymp for the shared contract.

Two-sided Wald p-value for H_0: \beta_T = \code{delta} vs. H_1: \beta_T \neq \code{delta}, using the inverse-variance-combined estimate and standard error from compute_estimate(). See InferenceAsymp for the shared Wald/asymptotic semantics.

Duplicate the robust-regression inference object while preserving the selected match-specific formulas and clearing cached fit results; see Inference for the common duplication contract.

Usage

ContinKKRobustRegrIVWCSource

Details

Fits a variance-weighted compound estimator for KK matching-on-the-fly designs with continuous responses using robust linear regression ('MASS::rlm') for the matched-pair and reservoir components separately.

Model. Two robust M/MM-estimator regressions are fit independently: one on the within-pair outcome differences for matched pairs (with covariate differences as predictors, no intercept), and one on the reservoir subjects (raw covariates plus a treatment indicator). Each yields a treatment-effect estimate \hat\beta_{T,k} and estimated variance. The two are combined by inverse-variance weighting into a single \hat\beta_T, the same combination rule used by InferenceContinKKOLSIVWC but with robust rather than OLS component fits. A component missing enough data (e.g. no matched pairs) is dropped from the combination.

Robust fitting. Uses MASS::rlm (or an internal Rcpp IRLS kernel when use_rcpp = TRUE, the default) with method = "M" or "MM"; "MM" (the default) uses an LQS-based high-breakdown start, while "M" can optionally warm-start from OLS (start_with_ols = TRUE). likelihood_tier = "quasi": the M/MM objective is not a normalized likelihood, so only Wald-type asymptotic inference is available (no score/gradient/likelihood-ratio testing types).

Assumptions. Continuous response; independent matched pairs and/or independent reservoir subjects; no censoring; a KK matching-on-the-fly design. Robust regression down-weights outlying residuals, trading some efficiency under exactly-Gaussian errors for resistance to heavy tails and contamination.

Value

Numeric scalar treatment-effect estimate on the outcome's natural scale.

A length-2 numeric vector c(lower, upper), or NA bounds if nonestimable.

Numeric scalar p-value in [0, 1], or NA_real_ if nonestimable.

References

Kapelner, A. and Krieger, A. M. (2014). Matching on-the-fly: Sequential allocation with higher power and efficiency. Biometrics, 70(2), 378-388. doi:10.1111/biom.12148. (KK14 in REFERENCES.md.)

See Also

Analogous Python API for robust linear models: statsmodels RLM. Robust regression (orientation).

Legacy class. Not fully tested in comprehensive_tests.R.

Count Composite Likelihood Inference Base

Description

Computes the treatment estimate.

Usage

CountCompositeLikelihoodSource

Details

Shared branch for count models whose reported estimator is robust or quasi-likelihood based.

Conditional-Poisson Inference for KK Designs with Combined Likelihood

Description

Initialize conditional-Poisson one-likelihood inference for KK count designs and prepare the combined likelihood used by InferenceCountKKCondPoissonOneLik.

Compute the conditional-Poisson one-likelihood treatment estimate by fitting the combined matched/reservoir likelihood and caching the treatment log-rate coefficient for related likelihood-test methods.

Recomputes the combined conditional-Poisson estimate under Bayesian-bootstrap weights.

Uses the shared asymptotic confidence-interval contract; see InferenceAsymp.

Uses the shared asymptotic two-sided p-value contract; see InferenceAsymp.

Uses the shared Wald confidence-interval contract; see InferenceAsymp.

Computes a Wald two-sided p-value.

Computes a design-adjusted score confidence interval.

Computes a design-adjusted likelihood-ratio confidence interval.

Computes a design-adjusted gradient confidence interval.

Computes a design-adjusted score p-value.

Computes a design-adjusted likelihood-ratio p-value.

Computes a design-adjusted gradient p-value.

Usage

CountKKCondPoissonOneLikLikelihoodSource

KK Hurdle Poisson Combined-Likelihood Inference for Count Responses

Description

Initialize KK hurdle-Poisson one-likelihood inference for count responses and prepare the combined matched/reservoir likelihood. See InferenceCountKKHurdlePoissonOneLik and InferenceParamBootstrap for related likelihood and bootstrap methods.

Compute the one-likelihood hurdle-Poisson treatment-effect estimate by fitting the combined count likelihood and caching the treatment log-rate coefficient for related p-value and interval methods.

Recomputes the combined hurdle-Poisson estimate under Bayesian-bootstrap weights.

Compute the configured asymptotic confidence interval for the one-likelihood hurdle-Poisson treatment coefficient, delegating to Wald, score, likelihood-ratio, or gradient paths as documented in InferenceCountLikelihood.

Computes a design-conservative score confidence interval.

Computes a design-conservative likelihood-ratio confidence interval.

Computes a design-conservative gradient confidence interval.

Compute the configured asymptotic two-sided p-value for the one-likelihood hurdle-Poisson treatment coefficient, delegating to Wald, score, likelihood-ratio, or gradient paths as documented in InferenceCountLikelihood.

Computes a design-conservative score p-value.

Computes a design-conservative likelihood-ratio p-value.

Computes a design-conservative gradient p-value.

Compute the Wald confidence interval for the one-likelihood hurdle-Poisson treatment coefficient, falling back to bootstrap when the model standard error is unavailable. See InferenceAsymp.

Compute the Wald two-sided p-value for the one-likelihood hurdle-Poisson treatment coefficient, falling back to the Bayesian-bootstrap p-value when the model standard error is unavailable. See InferenceAsymp.

Usage

CountKKHurdlePoissonOneLikLikelihoodSource

An Abstract Experimental Design

Description

Internal method. An abstract R6 Class encapsulating the data and functionality for an experimental design. This class takes care of data storage and response handling.

Details

Throughout the package, treatment assignment vectors w use the \{0, 1\} encoding: 1 indicates a treated subject and 0 a control subject. All public methods that return or accept w (e.g. get_w(), draw_ws_according_to_design()) use this convention. A handful of variance estimators (e.g. InferenceIncidCMH, InferenceIncidExtendedRobins) recode to a signed \{-1,+1\} contrast internally where their formulas require it; that recoding is local to those classes and does not affect this public convention.

Saving and loading

Design (and its DesignSeqOneByOne subclasses) is the unit of persistence for a trial. Persist a des_obj with base R's saveRDS()/readRDS() – there is no dedicated save_edi_design()/load_edi_design() wrapper, and none is planned: the audit behind this section found nothing that needs transformation on load beyond what is documented here. Inference* objects are disposable, cheaply reconstructed from a Design object on demand (see each class's $new()), and must never be saveRDS()'d directly – nothing currently prevents it (they serialize "successfully" like any R6 object), but the result is a frozen snapshot a user could easily mistake for something that stays live against the design, and re-running inference from a reloaded Design is both cheap and the only tested path.

Worked example (mirrors the round-trip tests in R/EDI/tests/testthat/test-save-load-design.R):

des_obj = DesignSeqOneByOneBernoulli$new(n = 20, response_type = "continuous")
for (i in 1:10) {
  des_obj$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1)))
  des_obj$add_one_subject_response(i, y = rnorm(1))
}
saveRDS(des_obj, "trial.rds", version = 2)

# ...new R session...
des_obj = readRDS("trial.rds")
for (i in 11:20) {
  des_obj$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1)))
  des_obj$add_one_subject_response(i, y = rnorm(1))
}
inf_obj = InferenceContinOLS$new(des_obj) # reconstructed fresh, never persisted
inf_obj$compute_estimate()

Passing version = 2 to saveRDS() is recommended, matching the one existing internal precedent for RDS serialization in this package (SimulationFramework's replication cache); it is not required for a same-R-version round trip.

Version stamp. Every Design object records the package version it was constructed under (get_edi_version_created()). This is stamped once at construction and is not refreshed by readRDS() – it reflects the version that originally built the object, not whatever version is currently loaded. The first "resume the trial" call after a reload (draw_ws_according_to_design() for fixed designs, add_one_subject_to_experiment_and_assign() for sequential designs) compares the stamped version's major component against the currently loaded package's major component and emits a one-time warning() on a mismatch; minor/patch differences are silent, since most field additions are additive under this class's lock_objects = FALSE R6 fields and do not warrant nagging on every routine upgrade. Objects saved before this field existed self-initialize it to the currently loaded version the first time it is read, rather than erroring on the missing field.

RNG/reproducibility caveat. private$seed is consumed only once, inside maybe_set_seed() at construction time, and is not re-applied on readRDS(). Continuing to enroll subjects after a reload therefore draws from whatever the global .Random.seed happens to be in the new session, not a deterministic continuation of the original stream. This is almost certainly the right behavior for a real trial (bit-for-bit-reproducible continuation across a process restart is not a property a production trial should have), but it means a same-seed reload-and-continue is not expected to reproduce the same draws as an uninterrupted run with that seed – do not rely on that for testing.

Known non-serializable case. A DesignFixedOptimal constructed with objective = "custom" from a raw RcppXPtrUtils::cppXPtr() external pointer (rather than a C++ source string) cannot be safely reloaded: compiled function pointers do not survive a saveRDS()/readRDS() round trip, and there is no retained source to recompile from. This is detected on first use after reload and raises a clear error rather than failing silently; supply custom_objective as a C++ source string instead of a pre-built cppXPtr() object if you need this design to survive a save/reload cycle – that form recompiles itself automatically the first time it is used post-reload. Every other audited private cache on Design and its components (all_subject_data_cache, permutations_cache, lin_centered_covariates, matching/blocking/cluster component state such as m, xm_structural, boot_pair_rows) was traced to its originating C++ return type and confirmed to hold only plain R matrices/vectors/lists, not external pointers or other non-serializable values.

Active bindings

Methods

Public methods

• Design$is_blocking_design()

• Design$is_matching_design()

• Design$is_a_kk_matching_capable()

• Design$is_a_cluster_capable()

• Design$is_a_bernoulli_capable()

• Design$new()

• Design$add_one_subject_response()

• Design$add_all_subject_responses()

• Design$overwrite_all_subject_assignments()

• Design$is_fixed_sample_size()

• Design$assert_all_subjects_arrived()

• Design$assert_all_responses_recorded()

• Design$check_experiment_completed()

• Design$assert_even_allocation()

• Design$assert_fixed_sample()

• Design$any_censoring()

• Design$has_general_censoring()

• Design$get_t()

• Design$get_X_raw()

• Design$get_X_imp()

• Design$get_X()

• Design$get_y()

• Design$get_y_original()

• Design$get_w()

• Design$draw_ws_according_to_design()

• Design$capabilities()

• Design$supports()

• Design$applicable_inference_class_names()

• Design$unavailable_inference_classes_due_to_missing_packages()

• Design$incompatible_inference_classes_due_to_design_structure()

• Design$randomization_family()

• Design$supports_resampling()

• Design$supports_randomization_draw()

• Design$supports_resampling_replay()

• Design$prepare_for_resampling_replay()

• Design$warm_all_subject_data_cache()

• Design$get_n()

• Design$get_y_L()

• Design$get_y_R()

• Design$get_effective_time()

• Design$get_effective_dead()

• Design$get_prob_T()

• Design$get_response_type()

• Design$get_response_type_original()

• Design$get_ordinal_levels()

• Design$get_original_ordinal_levels()

• Design$get_missingness_method()

• Design$get_edi_version_created()

• Design$transform_y()

• Design$get_design_formula()

• Design$duplicate()

• Design$clone()

Design$is_blocking_design()

Check whether this design currently has blocking structure.

The base implementation returns FALSE. Designs that compose BlockingStructure override this method with the structural check.

Usage

Design$is_blocking_design()

Returns

FALSE for designs without BlockingStructure.

Design$is_matching_design()

Check whether this design currently has matching structure.

The base implementation returns FALSE. Designs that compose MatchingStructure override this method with the structural check.

Usage

Design$is_matching_design()

Returns

FALSE for designs without MatchingStructure.

Design$is_a_kk_matching_capable()

Characterization: is this a KK matching-on-the-fly-capable design (sequential KK or its fixed binary-match equivalent)? Default FALSE; overridden to TRUE on DesignSeqOneByOneKK14 and DesignFixedBinaryMatch.

Usage

Design$is_a_kk_matching_capable()

Design$is_a_cluster_capable()

Characterization: is this a cluster-structured design? Default FALSE; overridden to TRUE on DesignFixedCluster and DesignFixedBlockedCluster.

Usage

Design$is_a_cluster_capable()

Design$is_a_bernoulli_capable()

Characterization: is this a Bernoulli-randomized design? Default FALSE; overridden to TRUE on DesignSeqOneByOneBernoulli and DesignFixedBernoulli.

Usage

Design$is_a_bernoulli_capable()

Design$new()

Initialize an experimental design

Usage

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

Arguments

Returns

A new 'Design' object

Design$add_one_subject_response()

For CARA designs, add a single subject response.

Usage

Design$add_one_subject_response(t, y = NULL, y_L = NULL, y_R = NULL)

Arguments

Design$add_all_subject_responses()

For non-CARA designs, add all subject responses.

Usage

Design$add_all_subject_responses(ys = NULL, y_Ls = NULL, y_Rs = NULL)

Arguments

Design$overwrite_all_subject_assignments()

For analysis on already-completed experimental data

Usage

Design$overwrite_all_subject_assignments(w)

Arguments

Design$is_fixed_sample_size()

Check if this design was initialized with a fixed sample size n

Usage

Design$is_fixed_sample_size()

Returns

TRUE if fixed.

Design$assert_all_subjects_arrived()

Asserts if all subjects arrived.

Usage

Design$assert_all_subjects_arrived()

Design$assert_all_responses_recorded()

Asserts if all responses are recorded.

Usage

Design$assert_all_responses_recorded()

Design$check_experiment_completed()

Checks if the experiment is completed.

Usage

Design$check_experiment_completed()

Returns

TRUE if experiment is complete, FALSE otherwise.

Design$assert_even_allocation()

Checks if the experiment has a 50-50 allocation.

Usage

Design$assert_even_allocation()

Design$assert_fixed_sample()

Checks if the experiment has a fixed sample size.

Usage

Design$assert_fixed_sample()

Design$any_censoring()

Checks if the experiment has any censored responses

Usage

Design$any_censoring()

Returns

TRUE if any censored.

Design$has_general_censoring()

Checks if the experiment has any left- or interval-censored survival responses – i.e. any subject whose y_R is finite (right-censored subjects have y_R = Inf, which is excluded). Most survival Inference classes cannot yet consume this shape of data (see get_effective_time()/get_effective_dead()); this is the check Inference$initialize() uses to reject construction cleanly for those classes.

Usage

Design$has_general_censoring()

Returns

TRUE if any subject is left- or interval-censored.

Design$get_t()

Get t

Usage

Design$get_t()

Returns

The current number of subjects.

Design$get_X_raw()

Get raw X information

Usage

Design$get_X_raw()

Returns

A data frame of subject data.

Design$get_X_imp()

Get imputed X information

Usage

Design$get_X_imp()

Returns

Same as Xraw except with imputations.

Design$get_X()

Get X matrix

Usage

Design$get_X()

Returns

A numeric matrix of subject data.

Design$get_y()

Get y

Usage

Design$get_y()

Returns

A numeric vector of subject responses.

Design$get_y_original()

Get y_original

Usage

Design$get_y_original()

Returns

A numeric vector of the original subject responses.

Design$get_w()

Get w

Usage

Design$get_w()

Returns

A {0,1} vector of subject assignments (1 = treated, 0 = control).

Design$draw_ws_according_to_design()

Draw treatment assignment vectors according to the design.

Usage

Design$draw_ws_according_to_design(r = 1L)

Arguments

Returns

A matrix of size n x r with {0,1} entries (1 = treated, 0 = control).

Design$capabilities()

Returns the capabilities this design instance exposes (see fix_design_hierarchy.md, "Capability Model").

Deliberately instance-level, not a class-registry read (fix_design_hierarchy.md, TODO-28): is_blocking_design()/is_matching_design() depend on real construction-time state (e.g. private$m/private$blocking_capable), not just which components a class composes – DesignFixediBCRD constructed with an unknown n, for instance, composes BlockingStructure but is not blocking-capable for that particular instance. A class-registry-only answer (this function briefly unioned in get_effective_design_capabilities(), a purely class-level, component- composition-based check) would silently report "blocking" for every instance of such a class regardless of its actual construction state – confirmed as a real, reproducible false positive during this TODO's implementation, not a hypothetical. get_effective_design_capabilities()/ design_class_registry.R's direct_components still exist and are correct – they're the right tool for a generator-only query with no instance in hand (see design_class_generator_supports_batch_w_pregeneration()), just not for this instance-level method.

Usage

Design$capabilities()

Returns

A character vector of capability names.

Design$supports()

Returns whether this design object supports a capability. See capabilities().

Usage

Design$supports(capability)

Arguments

Returns

TRUE if the capability is present, FALSE otherwise.

Design$applicable_inference_class_names()

Returns the sorted character vector of concrete, exported Inference class names legal for this design object under default constructor arguments, derived purely from this design's own normalized metadata (response type, KK-matching capability, blocking, and both censoring axes) filtered through the registry's compatibility predicates – the same normalization and predicate logic InferenceSuite uses for discovery (see normalize_inference_design_metadata() and is_inference_class_compatible_with_design_metadata() in inference_suite.R). No candidate class is constructed to determine applicability, so this has no side effects and cannot be influenced by a constructor failure or a missing optional package (see unavailable_inference_classes_due_to_missing_packages() for that case, reported separately). A class whose censoring tolerance depends on non-default constructor arguments (e.g. InferenceSurvivalCoxPHRegr only tolerates general censoring with testing_type = "wald") is listed here when its default configuration is compatible; a construction-time error for an incompatible non-default argument combination remains the documented behavior of that class's initialize().

Usage

Design$applicable_inference_class_names()

Returns

A sorted character vector of applicable Inference class names.

Design$unavailable_inference_classes_due_to_missing_packages()

Companion to applicable_inference_class_names(): returns the subset of otherwise design-compatible Inference classes that are excluded solely because a registered required_packages entry is not installed, as a named list (class name -> character vector of missing package names) – kept separate from plain design incompatibility so callers can tell "not applicable to this design" apart from "applicable, but an optional dependency isn't installed."

Usage

Design$unavailable_inference_classes_due_to_missing_packages()

Returns

A named list, class name -> missing package names; empty list if none.

Design$incompatible_inference_classes_due_to_design_structure()

Companion to applicable_inference_class_names(): returns the subset of otherwise design-compatible Inference classes that are excluded because they declared a design_compatibility_reason predicate (a design-*structure* requirement, e.g. even treatment allocation or equal block sizes, beyond what response type/KK/blocking/censoring metadata alone can express) and this design object fails it, as a named list (class name -> one-line reason string) – kept separate from plain design incompatibility and from a missing package for the same reason unavailable_inference_classes_due_to_missing_packages() is kept separate: so callers can tell exactly why a class is missing from applicable_inference_class_names() instead of only discovering it as a construction-time error.

Usage

Design$incompatible_inference_classes_due_to_design_structure()

Returns

A named list, class name -> reason string; empty list if none.

Design$randomization_family()

Returns this design object's registry-backed randomization family (see fix_design_hierarchy.md, "Class Metadata"), e.g. "kk14", "bernoulli", "rerandomization". Replaces class-identity (inherits()/is()) dispatch at call sites that need to distinguish design variants (see "Class-Identity Dispatch Replacement"). Returns NA_character_ if the class is not registered or is one of the unsplit/timing-root abstract bases.

Usage

Design$randomization_family()

Returns

A single character string (or NA_character_).

Design$supports_resampling()

Check if the design supports resampling at all – FALSE only for the abstract timing-family bases themselves (DesignFixed, DesignSeqOneByOne, and their custom-extension abstract bases) instantiated directly; TRUE for every concrete subclass, including ObservationalDesign. This is the general check for resampling methods that never need the design's own randomization mechanism – plain nonparametric bootstrap, Bayesian bootstrap, m-out-of-n bootstrap, PRW subsampling – which only resample already-observed units/rows and their fixed, observed assignment, so they remain valid and available even for a design with no randomization mechanism at all (see ObservationalDesign's class documentation: "resampling subjects with their observed, fixed assignment does not require a known randomization probability"). Contrast with supports_randomization_draw()/ supports_resampling_replay() below, which gate the narrower set of methods that actually do need to invoke the design's mechanism (a plain randomization test/CI, or a bootstrap randomization test that re-randomizes resampled data) and are therefore FALSE for ObservationalDesign specifically – see fix_design_hierarchy.md, "Observational Design Migration" for the live bug that split fixes.

Usage

Design$supports_resampling()

Returns

TRUE if supported.

Design$supports_randomization_draw()

Check if this design can draw a fresh treatment assignment from its own randomization mechanism – the eligibility condition for permutation-style randomization tests/CIs (compute_rand_two_sided_pval() and friends), which redraw w directly. FALSE for the abstract timing-family bases themselves (same as supports_resampling()) and, unlike supports_resampling(), also FALSE for ObservationalDesign (no draw mechanism at all – w is supplied by the user, so there is nothing to redraw); TRUE for every other concrete subclass. See supports_resampling()'s documentation for why this is a narrower, separate capability rather than reusing that one, and "Observational Design Migration" for the live bug this fixes (ObservationalDesign previously answered the old, unsplit supports_resampling() TRUE, silently passing the randomization-test eligibility assert before failing later and deeper, inside draw_ws_raw()'s throwing stub).

Usage

Design$supports_randomization_draw()

Returns

TRUE if a fresh randomization draw is supported.

Design$supports_resampling_replay()

Check if this design's mechanism can be faithfully replayed against resampled data – the eligibility condition specifically for the bootstrap randomization test (BRT), which resamples units and then re-randomizes each resample using the design's own mechanism (see inference_all_abstract_rand_bootstrap.R's repeated draw_ws_according_to_design() calls). Not the eligibility condition for plain nonparametric/Bayesian/m-out-of-n/PRW-subsampling bootstrap – those never redraw w at all (they resample already-observed units and their fixed, observed assignment) and are gated by the broader supports_resampling() instead, which stays TRUE for ObservationalDesign. FALSE for the same abstract timing-family bases as supports_randomization_draw() and for ObservationalDesign (no randomization mechanism to replay); TRUE for every other concrete subclass. See supports_randomization_draw()'s documentation for why this is a separate capability rather than the same flag reused.

Usage

Design$supports_resampling_replay()

Returns

TRUE if bootstrap-randomization-test-style replay is supported.

Design$prepare_for_resampling_replay()

Hook invoked by the bootstrap-randomization-test machinery on a design object whose assignment mechanism is about to be replayed against resampled data (once per replicate draw site, ahead of draw_ws_according_to_design(1L)). The base implementation is a no-op; designs whose replay is a full re-optimization (DesignFixedOptimal) override it to switch to their per-replicate solver profile (solver_args$brt_*). Idempotent.

Usage

Design$prepare_for_resampling_replay()

Returns

invisible(NULL).

Design$warm_all_subject_data_cache()

Warm the per-subject assignment-data cache, when this design uses covariates. This is an internal optimization hook for randomization inference; it keeps cache mutation inside the Design object instead of exposing its private environment to callers.

Usage

Design$warm_all_subject_data_cache()

Returns

TRUE invisibly when a cache warm-up was attempted, or FALSE invisibly when the design does not use covariates.

Design$get_n()

Get n, the sample size

Usage

Design$get_n()

Returns

The number of subjects.

Design$get_y_L()

Get y_L

Usage

Design$get_y_L()

Returns

A numeric vector of censored-response lower bounds (NA for exact-response subjects).

Design$get_y_R()

Get y_R

Usage

Design$get_y_R()

Returns

A numeric vector of censored-response upper bounds (NA for exact-response subjects).

Design$get_effective_time()

Get the effective response time per subject: the exact value y where recorded, or the lower bound y_L for a censored subject. This reconstructs "the one informative number" every response type other than left-/interval-censored survival data has always had, for code that needs a single numeric value per subject rather than the y/y_L/ y_R triple directly.

Usage

Design$get_effective_time()

Returns

A numeric vector, one value per subject.

Design$get_effective_dead()

Get the effective event indicator per subject: 1 for an exact response, 0 for a censored one. This reconstructs today's dead semantics for right-censored survival data (and is trivially all-1 for every other response type, which never has censoring). It is only valid for exact/right-censored data – a left- or interval-censored subject also returns 0 here, which is not meaningful right-censoring status, so callers must confirm (e.g. via any_censoring() plus their own censoring-shape checks) that no such rows are present before relying on this value.

Usage

Design$get_effective_dead()

Returns

An integer vector, one value per subject.

Design$get_prob_T()

Get probability of treatment

Usage

Design$get_prob_T()

Returns

The specified probability.

Design$get_response_type()

Get response type

Usage

Design$get_response_type()

Returns

The specified response type.

Design$get_response_type_original()

Get the original response type

Usage

Design$get_response_type_original()

Returns

The original specified response type.

Design$get_ordinal_levels()

Get ordinal levels

Usage

Design$get_ordinal_levels()

Returns

The levels of the ordinal response.

Design$get_original_ordinal_levels()

Get original ordinal levels

Usage

Design$get_original_ordinal_levels()

Returns

The labels for the levels of the original ordinal response.

Design$get_missingness_method()

Get the missingness method

Usage

Design$get_missingness_method()

Returns

The missingness handling method: "impute", "drop_column", or "error".

Design$get_edi_version_created()

Get the EDI package version this object was created under.

Stamped once, at construction time, from utils::packageVersion("EDI"); never re-stamped on readRDS() reload, so it reflects the version that originally built the object rather than whatever version is currently loaded. Objects saved before this field existed self-initialize it to the currently loaded version the first time it is read (there is no way to recover the true original version for those objects), rather than erroring on the missing field.

Usage

Design$get_edi_version_created()

Returns

A character string, e.g. "1.0.0".

Design$transform_y()

Transform the response vector y

Usage

Design$transform_y(
  transform_fun,
  transformed_response_type,
  ordinal_levels = NULL
)

Arguments

Design$get_design_formula()

Get the model formula

Usage

Design$get_design_formula()

Returns

The model formula.

Design$duplicate()

Duplicate this design object

Usage

Design$duplicate(verbose = FALSE)

Arguments

Returns

A new 'Design' object with the same data

Design$clone()

The objects of this class are cloneable with this method.

Usage

Design$clone(deep = FALSE)

Arguments

Examples

# Design is abstract and cannot be instantiated directly; construct a
# concrete subclass instead, e.g.:
seq_des = DesignSeqOneByOneBernoulli$new(n = 6, response_type = 'continuous')
seq_des$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1)))

Internal base for user-defined sequential-design extensions

Description

DesignCustomSequential is intentionally not exported. Subclasses implement assignment_rule() and return a scalar 0/1 assignment for the current subject. EDI handles subject storage, responses, and redraws through DesignSeqOneByOne.

Super classes

Design -> DesignSeqOneByOne -> DesignCustomSequential

Methods

Public methods

• DesignCustomSequential$assignment_rule()

• DesignCustomSequential$assign_wt()

• DesignCustomSequential$clone()

DesignCustomSequential$assignment_rule()

User-defined assignment rule.

Usage

DesignCustomSequential$assignment_rule()

Returns

A binary treatment assignment.

DesignCustomSequential$assign_wt()

Standard internal assignment entry point.

Usage

DesignCustomSequential$assign_wt()

Returns

A binary treatment assignment.

DesignCustomSequential$clone()

The objects of this class are cloneable with this method.

Usage

DesignCustomSequential$clone(deep = FALSE)

Arguments

A Fixed Design

Description

An abstract R6 Class encapsulating the data and functionality for a fixed experimental design. This class takes care of whole-experiment randomization.

Super class

Design -> DesignFixed

Methods

Public methods

• DesignFixed$new()

• DesignFixed$assign_w_to_all_subjects()

• DesignFixed$add_all_subjects_to_experiment()

• DesignFixed$add_all_subject_responses()

• DesignFixed$overwrite_all_subject_assignments()

• DesignFixed$clone()

DesignFixed$new()

Initialize a fixed experimental design

Usage

DesignFixed$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 'DesignFixed' object

DesignFixed$assign_w_to_all_subjects()

Assign treatment to all subjects in the fixed experiment.

Usage

DesignFixed$assign_w_to_all_subjects(w_precomputed = NULL)

Arguments

DesignFixed$add_all_subjects_to_experiment()

Add all subjects' covariates to a fixed design at once.

Usage

DesignFixed$add_all_subjects_to_experiment(X_all)

Arguments

Returns

Invisibly returns the design object.

DesignFixed$add_all_subject_responses()

Add all subject responses for a fixed design.

Usage

DesignFixed$add_all_subject_responses(ys = NULL, y_Ls = NULL, y_Rs = NULL)

Arguments

DesignFixed$overwrite_all_subject_assignments()

Overwrite all subject assignments for a fixed design.

Usage

DesignFixed$overwrite_all_subject_assignments(w)

Arguments

DesignFixed$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixed$clone(deep = FALSE)

Arguments

Examples

# DesignFixed is abstract and cannot be instantiated directly; construct a
# concrete subclass instead, e.g.:
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()

A Fixed-Sample-Size Bernoulli (Independent-Coin-Flip) Randomized Design

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

A Fixed, Non-Bipartite-Matched-Pair Design with Within-Pair Randomization

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

A Fixed, Blocked-and-Clustered Randomized Design

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

A Fixed, Stratified-Block Randomized Design

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

A Fixed, Unblocked Cluster Randomized Design

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

Internal base for user-defined fixed-design extensions

Description

DesignFixedCustom is intentionally not exported. Subclasses implement draw_assignments(r = 1) and return an n x r 0/1 assignment matrix. EDI handles subject storage, responses, and validation through DesignFixed.

Super classes

Design -> DesignFixed -> DesignFixedCustom

Methods

Public methods

• DesignFixedCustom$draw_assignments()

• DesignFixedCustom$clone()

DesignFixedCustom$draw_assignments()

Draw assignments from the custom design.

Usage

DesignFixedCustom$draw_assignments(r = 1)

Arguments

Returns

An n x r matrix of 0/1 assignments.

DesignFixedCustom$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedCustom$clone(deep = FALSE)

Arguments

A Fixed, Balanced Two-Arm Factorial Design

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

A Fixed, Covariate-Balanced Design via Greedy Pairwise-Swap Search

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

A Fixed, Model-Based Optimal Design via Greedy Pairwise-Exchange Search

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

A Fixed, Matched-Pair Design with Greedy Which-Member-Treated Optimization

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

A Fixed, Deterministic Single-Allocation Optimal Design

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 use the per-replicate solver profile: solver_args$brt_solver (default "annealing" with the reduced brt_max_iter/brt_n_chains schedule – replicate assignments need to be faithful applications of the mechanism, not individually re-verified to the observed solve's convergence standard; "ompr" buys exact per-replicate solves at the user's expense). 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()
}

A Fixed, Covariate-Homogeneous-Block Randomized Design

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

DesignFixedOptimalBlocks$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 block-formation cost (K-way anticlustering, greedy matching, or the exact ompr/GLPK solve) once per cell and reusing the resulting block assignment across replicates, rather than recomputing it per replicate.

Usage

DesignFixedOptimalBlocks$supports_batch_w_pregeneration()

Returns

Always TRUE for this class.

DesignFixedOptimalBlocks$new()

Initialize a fixed optimal-blocks design. Block formation itself is deferred until the first draw (see class documentation); this constructor only validates and records configuration, including checking that B (or its floor(sqrt(n)) default) admits a feasible block-size partition of n when n is already known.

Usage

DesignFixedOptimalBlocks$new(
  B = NULL,
  method = "K-way",
  dist = "mahal",
  roi_solver = "glpk",
  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 DesignFixedOptimalBlocks object.

DesignFixedOptimalBlocks$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedOptimalBlocks$clone(deep = FALSE)

Arguments

References

Higgins, M. J., Sävje, F., and Sekhon, J. S. (2016). "Improving massive experiments with threshold blocking." Proceedings of the National Academy of Sciences, 113(27), 7369-7376, doi:10.1073/pnas.1510504113, for optimal/near-optimal covariate-based blocking prior to randomization. See also randomized block design for orientation and Mahalanobis distance for the default "ompr" distance.

Examples

des = DesignFixedOptimalBlocks$new(n = 9, response_type = 'continuous')
des$add_all_subjects_to_experiment(data.frame(x = rnorm(9)))
des$assign_w_to_all_subjects()

A Fixed Rerandomization Design (Rejection-Sampled on Covariate Balance)

Description

A fixed-sample-size DesignFixed implementing rerandomization (Morgan and Rubin, 2012): candidate allocations w are drawn from the design's base randomization law (balanced complete randomization when prob_T = 0.5, i.i.d. \mathrm{Bernoulli}(prob\_T) draws otherwise — see generate_one_rerandomized_w()) and only accepted if a covariate imbalance criterion M(w) between the treated and control groups falls below a threshold a (obj_val_cutoff), i.e. the accepted allocations are drawn from the base randomization distribution truncated to \{w : M(w) \le a\}. Unlike DesignFixedGreedy/ DesignFixedGreedyDOptimal, which search for a single well-balanced allocation, rerandomization instead filters the design's own randomization distribution, which is what makes it directly compatible with Fisherian/randomization-based inference (the accepted allocations remain a well-defined — if truncated — randomization distribution, valid for randomization tests/CIs restricted to that truncated support).

Two mutually exclusive acceptance modes are supported (specifying both errors): obj_val_cutoff accepts/rejects each draw against a fixed threshold a; prop_acceptable instead draws r / prop\_acceptable candidates and keeps the r with the lowest M(w) (an empirical top-quantile acceptance region, equivalent in the large-draw limit to an implied cutoff at the prop_acceptable quantile of M(w)'s distribution under the base randomization law).

Objective M(w). objective = "mahal_dist" (default) uses the squared Mahalanobis distance between treated and control covariate means, M(w) = (\bar X_T - \bar X_C)^\top S^{-1} (\bar X_T - \bar X_C), where S is the sample covariance of all covariates (ridge-regularized by 10^{-6}I if |\det S| < 10^{-10}), computed once and cached in private$S_inv. objective = "abs_sum_diff" instead uses the sum of absolute mean differences, M(w) = \sum_j |\bar X_{T,j} - \bar X_{C,j}|, with no correlation adjustment. Only these two objectives are supported; any other value errors at draw time.

Fast path (native C++). When prob_T = 0.5 and n is even, candidate generation and filtering run via a parallel C++ rejection sampler (rerandomization_search_cpp()), which internally works with a rescaled objective f_{\mathrm{cpp}}: f_{\mathrm{cpp}} = M(w)/4 for "mahal_dist" and f_{\mathrm{cpp}} = M(w)/2 (on a GED-standardized scale) for "abs_sum_diff"; the user-facing obj_val_cutoff is converted to this internal scale before being passed to C++, so the accepted-allocation semantics are unaffected, but this rescaling is a backend implementation detail worth knowing when comparing C++-path and pure-R-path acceptance rates for the same nominal cutoff. The sampler draws up to max(r * 1000, 100000) candidates internally; if fewer than r allocations are accepted within that budget (an overly tight cutoff), this errors naming how many were actually found – loosen obj_val_cutoff or use prop_acceptable instead. (Earlier versions silently recycled the accepted set to pad out to r, duplicating some draws; fixed, since that meant some "independent" replicates were literal duplicates of an accepted allocation.)

Seed reproducibility and multi-core parallelism. The C++ fast path's rejection sampler is a genuine work-stealing search: with more than one core (set_num_cores/a fork cluster/mirai daemons; the package default is a single core), threads race via atomic operations for both which candidate draws to try next and which output column an accepted draw claims, so which per-thread-seeded RNG stream ends up producing a given replicate – and in what order – depends on real-time OS scheduling, not just seed. With the default single core, draws are exactly seed-reproducible; this is not guaranteed once more than one core is in use. Contrast with DesignFixedGreedy/ DesignFixedBinaryMatch, whose C++ kernels use static (not work-stealing) thread scheduling and remain seed-reproducible regardless of core count.

prop_acceptable path. Uses complete_randomization_forced_balanced_cpp() (balanced case) or complete_randomization_imbalanced_cpp() (prob_T != 0.5) to draw n_{\mathrm{draw}} = \mathrm{round}(r / prop\_acceptable) candidate allocations in one batched call, computes M(w) for all of them via compute_objective_vals_cpp(), and keeps the r with smallest M(w).

Pure-R fallback (unbalanced or odd n, obj_val_cutoff mode only). Draws one candidate at a time via generate_one_rerandomized_w() in an unbounded repeat loop that accepts the first candidate with M(w) \le a. Unlike the C++ fast path, this fallback has no draw-count safety limit: if obj_val_cutoff is set tight enough that acceptance probability under the base randomization law is extremely small for this n/ covariate structure, this loop can run for a very long time (in principle indefinitely) before finding an acceptable draw.

Super classes

Design -> DesignFixed -> DesignFixedRerandomization

Methods

Public methods

• DesignFixedRerandomization$new()

• DesignFixedRerandomization$clone()

DesignFixedRerandomization$new()

Initialize a rerandomization fixed experimental design. Exactly one of obj_val_cutoff/prop_acceptable may be specified (or neither, which accepts every candidate, i.e. no filtering); supplying both raises an error. See class documentation for the exact acceptance semantics of each mode and the covariate-imbalance objective.

Usage

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

Arguments

Returns

A new 'DesignFixedRerandomization' object

DesignFixedRerandomization$clone()

The objects of this class are cloneable with this method.

Usage

DesignFixedRerandomization$clone(deep = FALSE)

Arguments

References

Morgan, K. L., and Rubin, D. B. (2012). "Rerandomization to improve covariate balance in experiments." The Annals of Statistics, 40(2), 1263-1282, doi:10.1214/12-AOS1008, for the rerandomization framework and its randomization-inference validity. See also Mahalanobis distance for the default objective.

Examples

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

A Fixed, Individually Balanced Completely Randomized Design (iBCRD)

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

Sequential One-by-One Experimental Design

Description

Abstract R6 class encapsulating data and functionality for a sequential one-by- one experimental design.

Sample size and stopping

Subjects are assigned one at a time, but this class does not implement interim outcome monitoring or an outcome-dependent stopping rule. For the usual fixed-sample analysis, specify the target sample size n before enrollment and stop after exactly n subjects; the caller is responsible for ending enrollment at that point. With n = NULL, the class leaves the final sample size unspecified and does not determine when enrollment ends. Inference methods that assume a fixed sample size require the final size to be chosen independently of accumulating outcomes.

Super class

Design -> DesignSeqOneByOne

Methods

Public methods

• DesignSeqOneByOne$new()

• DesignSeqOneByOne$add_one_subject()

• DesignSeqOneByOne$add_one_subject_to_experiment_and_assign()

• DesignSeqOneByOne$assign_wt()

• DesignSeqOneByOne$print_current_subject_assignment()

• DesignSeqOneByOne$clone()

DesignSeqOneByOne$new()

Initialize a sequential one-by-one design.

Usage

DesignSeqOneByOne$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

DesignSeqOneByOne$add_one_subject()

Add subject-specific measurements for the next subject entrant.

Usage

DesignSeqOneByOne$add_one_subject(x_new, allow_new_cols = TRUE)

Arguments

DesignSeqOneByOne$add_one_subject_to_experiment_and_assign()

Adds a subject and assigns treatment.

Usage

DesignSeqOneByOne$add_one_subject_to_experiment_and_assign(x_new)

Arguments

Returns

The treatment assignment as {0,1} (1 = treated, 0 = control).

DesignSeqOneByOne$assign_wt()

Assigns treatment to the current subject.

Usage

DesignSeqOneByOne$assign_wt()

Returns

The treatment assignment (0 or 1).

DesignSeqOneByOne$print_current_subject_assignment()

Prints the current subject's assignment.

Usage

DesignSeqOneByOne$print_current_subject_assignment()

DesignSeqOneByOne$clone()

The objects of this class are cloneable with this method.

Usage

DesignSeqOneByOne$clone(deep = FALSE)

Arguments

Examples

# DesignSeqOneByOne is abstract and cannot be instantiated directly;
# construct a concrete subclass instead, e.g.:
seq_des = DesignSeqOneByOneBernoulli$new(n = 6, response_type = 'continuous')
seq_des$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1)))

Atkinson's (1982) Covariate-Adjusted Biased Coin Sequential Design

Description

A DesignSeqOneByOne that assigns each newly arriving subject's treatment via Atkinson's (1982) D_A-optimum biased coin: a coin whose treatment probability is skewed away from prob_T toward whichever assignment would most improve the current design's efficiency for estimating the treatment effect D_A-optimally, given the covariates observed so far. Compared to a fixed-probability coin (e.g. DesignSeqOneByOneBernoulli), this improves covariate balance/estimation efficiency online without ever fully determinizing the assignment (the coin is always strictly between 0 and 1, so randomization-based inference remains valid), at the cost of requiring a numerically well-conditioned design matrix to compute the bias.

Assignment rule. For subject t, let Z_{t-1} = [w_{1:t-1}, 1, X_{1:t-1}] be the (treatment, intercept, covariates) design matrix accumulated from the first t-1 subjects, and let M = (t-1)(Z_{t-1}^\top Z_{t-1})^{-1}. Writing x_t for the new subject's covariate vector (with a leading 1 for the intercept) and A = M_{[1, 2:]} \cdot x_t (the treatment row of M, projected onto x_t), the treatment probability is

\pi_t = \frac{\big(M_{11}/A + 1\big)^2}{\big(M_{11}/A + 1\big)^2 + 1},

clamped to [0, 1], and subject t is assigned to treatment with probability \pi_t. This is Atkinson's biased-coin formula for D_A-optimal sequential design: the coin biases toward the assignment that would most reduce the variance of the treatment-effect estimate under the linear model implied by Z_t, converging toward more extreme (but never fully deterministic) probabilities as the current covariate imbalance grows in directions that matter for that estimate.

Fallback to a fair(-ish) coin. For the first ncol(private$Xraw) + 3 subjects (too few observations for Z_{t-1}^\top Z_{t-1} to be reliably invertible), and whenever the C++ computation encounters a non-invertible design matrix, a non-finite bias term, or any other numerical failure (caught via tryCatch()), assignment falls back to an unbiased \mathrm{Bernoulli}(prob\_T) draw instead of Atkinson's rule.

Reproducibility. The per-subject C++ draw (atkinson_assign_weight_cpp()) seeds its own generator from R's RNG stream per call, so seed governs reproducibility of the resulting assignment sequence in the usual way.

Super classes

Design -> DesignSeqOneByOne -> DesignSeqOneByOneAtkinson

Methods

Public methods

• DesignSeqOneByOneAtkinson$new()

• DesignSeqOneByOneAtkinson$assign_wt()

• DesignSeqOneByOneAtkinson$clone()

DesignSeqOneByOneAtkinson$new()

Initialize an Atkinson (1982) biased-coin sequential experimental design (see class documentation for the assignment rule).

Usage

DesignSeqOneByOneAtkinson$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 'DesignSeqOneByOneAtkinson' object

DesignSeqOneByOneAtkinson$assign_wt()

Draw the next subject's treatment assignment via Atkinson's (1982) D_A-optimum biased coin (see class documentation for the exact probability formula), falling back to an unbiased \mathrm{Bernoulli}(prob\_T) draw early in the trial or on numerical failure of the biased-coin computation.

Usage

DesignSeqOneByOneAtkinson$assign_wt()

Returns

The treatment assignment (0 or 1) for the next subject.

DesignSeqOneByOneAtkinson$clone()

The objects of this class are cloneable with this method.

Usage

DesignSeqOneByOneAtkinson$clone(deep = FALSE)

Arguments

References

Atkinson, A. C. (1982). "Optimum biased coin designs for sequential clinical trials with prognostic factors." Biometrika, 69(1), 61-67, doi:10.1093/biomet/69.1.61. See also randomized experiment for orientation on biased-coin sequential designs.

Examples

seq_des = DesignSeqOneByOneAtkinson$new(n = 6, response_type = 'continuous')
seq_des$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1)))

A Sequential Bernoulli (Independent-Coin-Flip) Randomized Design

Description

A DesignSeqOneByOne in which each arriving subject's treatment assignment is drawn independently as w_t \stackrel{iid}{\sim} \mathrm{Bernoulli}(prob\_T), with no dependence on covariates or on prior assignments — the direct sequential-enrollment analog of DesignFixedBernoulli. As in the fixed-sample version, the realized number of treated subjects after t arrivals is random (\mathrm{Binomial}(t, prob\_T)), in contrast to sequential designs that actively balance assignment counts or covariates (e.g. DesignSeqOneByOneAtkinson).

Nonparametric bootstrap

The ordinary row bootstrap for this design is supported under a prespecified fixed sample size: choose n before enrollment and stop after exactly n subjects, without using interim outcomes to decide when to stop. EDI does not implement sequential monitoring or check that this stopping condition was followed. In particular, n = NULL does not satisfy the documented fixed-sample justification, even though the bootstrap method is not blocked at runtime. The usual assumptions of iid subjects and potential outcomes, and a regular estimator, also apply.

Super classes

Design -> DesignSeqOneByOne -> DesignSeqOneByOneBernoulli

Methods

Public methods

• DesignSeqOneByOneBernoulli$is_a_bernoulli_capable()

• DesignSeqOneByOneBernoulli$new()

• DesignSeqOneByOneBernoulli$assign_wt()

• DesignSeqOneByOneBernoulli$clone()

DesignSeqOneByOneBernoulli$is_a_bernoulli_capable()

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

Usage

DesignSeqOneByOneBernoulli$is_a_bernoulli_capable()

Returns

Always TRUE for this class.

DesignSeqOneByOneBernoulli$new()

Initialize a Bernoulli (independent-coin-flip) sequential experimental design.

Usage

DesignSeqOneByOneBernoulli$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 'DesignSeqOneByOneBernoulli' object

DesignSeqOneByOneBernoulli$assign_wt()

Draw the next subject's treatment assignment as a single independent \mathrm{Bernoulli}(prob\_T) coin flip (see class documentation); does not consult covariates or prior assignments.

Usage

DesignSeqOneByOneBernoulli$assign_wt()

Returns

The treatment assignment (0 or 1) for the next subject.

DesignSeqOneByOneBernoulli$clone()

The objects of this class are cloneable with this method.

Usage

DesignSeqOneByOneBernoulli$clone(deep = FALSE)

Arguments

Examples

seq_des = DesignSeqOneByOneBernoulli$new(n = 6, response_type = 'continuous')
seq_des$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1)))

Efron's (1971) Biased Coin Sequential Design

Description

A DesignSeqOneByOne implementing Efron's (1971) biased coin: no covariates are used, only the running counts of treated (n_T) and control (n_C) subjects assigned so far. If the counts are currently equal, the next subject is assigned by a fair \mathrm{Bernoulli}(0.5) coin; otherwise, the next subject is assigned to the currently under-represented group with probability weighted_coin_prob (> 0.5, e.g. the classical 2/3) and to the over-represented group with probability 1 - weighted_coin_prob. This keeps the running treatment/control counts close to balanced throughout enrollment (unlike DesignSeqOneByOneBernoulli, whose running counts can drift arbitrarily far from balanced) while remaining strictly randomized at every step (the coin is always strictly between 1 - weighted_coin_prob and weighted_coin_prob, never fully deterministic), unlike a purely deterministic alternating allocation. This is a count-balancing design only — it does not use covariates at all, in contrast to DesignSeqOneByOneAtkinson/ DesignSeqOneByOneKK21, which bias the coin toward covariate balance rather than (or in addition to) count balance.