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

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/new_feature_plans/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).

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.

Super classes

Design -> DesignFixed -> DesignFixedGreedyDOptimal

Methods

Public methods

DesignFixedGreedyDOptimal$new()
DesignFixedGreedyDOptimal$get_objective()
DesignFixedGreedyDOptimal$get_interest()
DesignFixedGreedyDOptimal$get_prior_precision()
DesignFixedGreedyDOptimal$clone()

+ inherited public methods from DesignFixed

+ inherited public methods from Design

`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

response_type: "continuous", "incidence", "proportion", "count", "survival", or "ordinal". Determines only which downstream inference/response machinery this design is paired with; it does not affect the optimality search itself.
prob_T: Probability of treatment assignment, in $(0, 1)$. The search fixes the treated count at $\mathrm{round}(n \cdot prob_T)$.
objective: The optimality criterion: "D" (default, determinant) or "A" (trace). See the class documentation for the exact criteria and for why objective = "A" with interest = "treatment" is equivalent to the default.
interest: Which parameters the criterion targets: "treatment" (default), "all", a one-sided formula (e.g. ~ x1 + x2), a single formula string (e.g. "x1 * x2 + x7", promoted to ~ x1 * x2 + x7), or a character vector of model-matrix column names – all but "all" meaning the treatment coefficient plus the named covariate coefficients (D_s/A_s; see class documentation, including why subset-D selects the same allocations as the default). Formula terms (including interactions like x1:x2) must correspond to columns of the design's model matrix: to target an interaction coefficient, the interaction must be in design_formula too – you cannot be "interested in" a coefficient the working model does not contain. Contrast matrices (general D_A) arrive with Stage 2 of the merge plan and currently raise an error.
prior_precision: NULL (default, non-Bayesian), a single positive scalar $\tau$ (ridge prior precision on the covariate coefficients only; treatment and intercept unpenalized), or a full $(1+p) \times (1+p)$ symmetric prior-precision matrix $R_0$ over $[\mathrm{intercept}, \mathrm{covariates}]$.
standardize_covariates: If TRUE (default) and prior_precision is a scalar, covariates are centered and scaled to unit variance before the penalized criterion matrices are built. Ignored otherwise.
n_iter: Number of exchange iterations. Inf (default) runs the exhaustive best-improvement search to a strict local optimum. Finite values (the stochastic swap mode shared with DesignFixedGreedy) arrive with the Stage-2 shared search engine and currently raise an error.
include_is_missing_as_a_new_feature: Flag for missingness indicators.
n: Sample size (if fixed).
verbose: Flag for verbosity.
missingness_method: How to handle missing values in covariates.
design_formula: A formula object.
seed: Integer seed for reproducibility. Unlike the former DesignFixedDOptimal/DesignFixedAOptimal documentation claimed, the optimality search is reproducible via seed (see class documentation).

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

deep: Whether to make a deep clone.

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