A Fixed, Balanced Two-Arm Factorial Design

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

+ inherited public methods from DesignFixed

• DesignFixed$add_all_subject_responses()
• DesignFixed$add_all_subjects_to_experiment()
• DesignFixed$assign_w_to_all_subjects()
• DesignFixed$overwrite_all_subject_assignments()

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

---

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

factors

A list where names are factor names and values are number of levels (e.g. list(treatment = 2)). The product of levels across all factors must currently equal exactly 2 (two-arm only).

response_type

The data type of response values.

include_is_missing_as_a_new_feature

Flag for missingness indicators.

n

The sample size.

verbose

Flag for verbosity.

missingness_method

How to handle missing values in covariates.

design_formula

A formula object.

seed

Integer seed for reproducibility.

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

deep

Whether to make a deep clone.

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