A Fixed, Stratified-Block Randomized Design
Source:R/design_fixed_blocking.R
DesignFixedBlocking.RdA 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.
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.
Super classes
Design -> DesignFixed -> DesignFixedBlocking
Methods
+ inherited public methods from DesignFixed
+ inherited public methods from Design
Design$add_one_subject_response()Design$any_censoring()Design$applicable_inference_class_names()Design$assert_all_responses_recorded()Design$assert_all_subjects_arrived()Design$assert_even_allocation()Design$assert_fixed_sample()Design$capabilities()Design$check_experiment_completed()Design$draw_ws_according_to_design()Design$duplicate()Design$get_X()Design$get_X_imp()Design$get_X_raw()Design$get_design_formula()Design$get_edi_version_created()Design$get_effective_dead()Design$get_effective_time()Design$get_missingness_method()Design$get_n()Design$get_ordinal_levels()Design$get_original_ordinal_levels()Design$get_prob_T()Design$get_response_type()Design$get_response_type_original()Design$get_t()Design$get_w()Design$get_y()Design$get_y_L()Design$get_y_R()Design$get_y_original()Design$has_general_censoring()Design$incompatible_inference_classes_due_to_design_structure()Design$is_a_bernoulli_capable()Design$is_a_cluster_capable()Design$is_a_kk_matching_capable()Design$is_blocking_design()Design$is_fixed_sample_size()Design$is_matching_design()Design$prepare_for_resampling_replay()Design$randomization_family()Design$supports()Design$supports_randomization_draw()Design$supports_resampling()Design$supports_resampling_replay()Design$transform_y()Design$unavailable_inference_classes_due_to_missing_packages()Design$warm_all_subject_data_cache()
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
strata_colsA character vector of column names to use for stratification. If `NULL` (the default), all available covariate columns are used.
response_type"continuous", "incidence", "proportion", "count", "survival", or "ordinal".
prob_TProbability of treatment assignment.
include_is_missing_as_a_new_featureFlag for missingness indicators.
nThe sample size.
preferred_num_bins_for_continuous_covariateThe number of quantile bins to use for continuous strata. Default is 2.
B_targetThe target number of blocks. Columns from `strata_cols` are added greedily in order, each column being included only if it does not push the total number of unique blocks beyond this target. For categorical covariates their natural levels are used; for continuous covariates `preferred_num_bins_for_continuous_covariate` quantile bins are used. Earlier columns are always preferred over later ones. When `n` is known at construction time, the default is the largest divisor of `n` that is at most `floor(sqrt(n))` (so the default always satisfies `equal_block_sizes = TRUE`); if `n` is not yet known, it is resolved to `floor(sqrt(n))` when subjects are added. Set `B_target = NULL` to use all columns unconditionally. An explicitly supplied `B_target` that does not divide `n` still errors immediately when `equal_block_sizes = TRUE`. Set `exact_num_blocks = TRUE` to hard fail if the final key construction does not produce exactly `B_target` blocks.
exact_num_blocksWhether to require the greedy key construction to produce exactly `B_target` blocks. Default `FALSE`.
equal_block_sizesWhether to require all blocks to have the same number of subjects. Default `TRUE`. When `TRUE` and both `n` and `B_target` are known at construction time, an error is raised immediately if `n` is not divisible by `B_target`. A second check fires when subjects are added: if the covariate-based strata produce unequal block counts the design errors at that point. Set to `FALSE` to allow unequal blocks (note that `InferenceIncidCMH` and `InferenceIncidExtendedRobins` still require equal block sizes regardless).
mOptional integer vector of explicit block identifiers, one per subject. If supplied, `n` must also be supplied and `length(m)` must equal `n`. The constructor then records this blocking structure immediately via `set_m()`, bypassing covariate-derived strata construction.
verboseA flag for verbosity.
missingness_methodHow to handle missing values in covariates.
design_formulaA formula object.
seedInteger seed for reproducibility.
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()