Type:	Package
Title:	Convex Optimal Designs for Group Testing Experiments
Version:	0.1.0
Description:	Finite candidate-set approximate optimal designs for group testing and related experiments, using convex optimization and equivalence checks. Implements the information matrix and cost structure for the prevalence / sensitivity / specificity model used in Huang and colleagues (2020), as in Chi-Kuang Yeh, Weng Kee Wong, and Julie Zhou (<doi:10.48550/arXiv.2508.08445>).
URL:	https://github.com/chikuang/gtDesign, https://arxiv.org/abs/2508.08445
License:	GPL-3
BugReports:	https://github.com/chikuang/gtDesign/issues
Encoding:	UTF-8
RoxygenNote:	7.3.3
Imports:	CVXR (≥ 1.8.1), tibble, MASS
Suggests:	testthat (≥ 3.0.0), dplyr, knitr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-04-03 17:13:36 UTC; chikuang
Author:	Chi-Kuang Yeh [aut, cre], Julie Zhou [aut], Weng Kee Wong [ctb]
Maintainer:	Chi-Kuang Yeh <cyeh@gsu.edu>
Repository:	CRAN
Date/Publication:	2026-04-09 15:40:08 UTC

A-optimal approximate design for group testing experiments

Description

A-optimal approximate design for group testing experiments

Usage

calc_Aopt(u, f, solver = "CLARABEL", ..., drop_tol = 1e-08)

Arguments

Value

An object of class "gt_a_design" and "gt_design".

D-optimal approximate design for group testing experiments

Description

Computes a D-optimal approximate design on a finite candidate set. The regression map f typically encodes contributions to the Fisher information matrix (e.g. score vectors or square-root information); see gt_huang2020_regressor() for the Huang et al.\ (2020) three-parameter model.

Usage

calc_Dopt(
  u,
  f,
  solver = "CLARABEL",
  ...,
  drop_tol = 1e-08,
  ridge = 1e-08,
  use_matrix_form = FALSE
)

Arguments

Value

An object of class "gt_d_design" and "gt_design".

E-optimal approximate design for group testing experiments

Description

Minimizes -\lambda_{\min}(\mathbf{M}) over \mathbf{w} on a finite candidate set via CVXR::Minimize(-CVXR::lambda_min(...)). The reported objective is \mathrm{loss}(\mathbf{M}) = -\lambda_{\min}(\mathbf{M}), matching MATLAB loss = -lambda_min(FIM) (e.g.\ calc_loss_E).

Usage

calc_Eopt(u, f, solver = "CLARABEL", ..., drop_tol = 1e-08, ridge = 1e-08)

Arguments

Details

This matches compute_design_SO() with criterion = "E" (same scalar loss).

Value

An object of class "gt_e_design" and "gt_design". Components value and optval are the minimization objective -\lambda_{\min}(\mathbf{M}): value is recomputed at the cleaned support, optval is the solver optimum of the minimize objective (they may differ slightly after drop_tol).

Examples

# Huang et al. (2020) model on {1,...,61}, q = 0 (same setting as D-opt example)
theta <- c(p0 = 0.07, p1 = 0.93, p2 = 0.96)
u <- seq_len(61L)
f <- gt_huang2020_regressor(theta, q = 0)
res_E <- calc_Eopt(u, f, drop_tol = 1e-6)
res_E$design
res_E$value # = -lambda_min(M), same as -min(eigen(M)$values)
-res_E$value # lambda_min(M) at the optimum
res_E$status

c-optimal approximate design for group testing experiments

Description

c-optimal approximate design for group testing experiments

Usage

calc_copt(u, f, cVec, solver = "CLARABEL", ..., drop_tol = 1e-10)

Arguments

Value

An object of class "gt_c_design" and "gt_design".

Directional derivatives on a finite candidate set

Description

Directional derivatives on a finite candidate set

Usage

calc_directional_derivatives(
  u,
  M,
  f,
  criteria = c("D"),
  cVec = NULL,
  use_ginv = TRUE,
  eig_tol = NULL
)

Arguments

Value

A named list of directional derivative vectors.

E-optimality

Implements d_E from Sec.\ 4 (Eq.\ (9)) of Yeh, Wong, and Zhou (arXiv:2508.08445): with orthonormal \mathbf{Q}(\mathbf{w}) spanning the eigenspace of \lambda_{\min}(\mathbf{M}) and multiplicity r^*, uses \mathbf{B} = (1/r^*)\mathbf{I}_{r^*} (trace one, positive semi-definite), so

d_E(u_i,\mathbf{w}) = \frac{1}{r^*}\|\mathbf{Q}^\top \mathbf{f}(u_i)\|^2 - \lambda_{\min}(\mathbf{M}).

When r^*=1, this is (\mathbf{v}^\top \mathbf{f}(u_i))^2 - \lambda_{\min}(\mathbf{M}) for a unit eigenvector \mathbf{v}.

Eta weights for the maximin equivalence theorem

Description

Solves for nonnegative weights in the maximin equivalence theorem. The returned vector eta satisfies the normalization condition induced by the derivative of the active right-hand sides and enforces a nonpositive weighted combination of directional derivatives across the candidate set.

Usage

calc_eta_weights_maximin(
  tstar,
  loss_ref,
  loss_model,
  directional_derivatives,
  criteria,
  q,
  tol = 1e-06,
  complementary_slack = TRUE,
  fallback_no_slack = TRUE,
  complementary_tol_mult = 100,
  solver = "CLARABEL",
  solvers_fallback = c("SCS", "ECOS"),
  ...
)

Arguments

Details

The linear program from Gao et al.\ also imposes approximate complementary slackness ⁠|eta_k * gap_k| <= tol⁠. With tight tol, that set can be empty together with the normalization constraint (common with three or more criteria). By default this function retries without complementary slackness if the strict problem is infeasible, and cycles a few solvers (works well with CVXR 1.8.x).

Value

A named numeric vector of eta weights.

Weighted multi-objective directional derivative

Description

Weighted multi-objective directional derivative

Usage

calc_multi_directional_derivative(dd_list, eta)

Arguments

Value

A numeric vector of combined directional derivative values.

Check the equivalence theorem on a finite candidate set

Description

Uses the same directional derivatives as calc_directional_derivatives() with a single criterion. For maximin designs, use check_equivalence_maximin().

Usage

check_equivalence(design_obj, f, u = NULL, tol = 1e-06, use_ginv = TRUE)

Arguments

Value

A list with directional derivative values and theorem checks.

Check the equivalence theorem for a maximin design

Description

Computes the weighted combined directional derivative \sum_j \eta_j d_j(x) over the candidate set and checks whether it is nonpositive, with approximate equality at the support points.

Usage

check_equivalence_maximin(
  design_obj,
  directional_derivatives,
  eta,
  tol = 1e-06
)

Arguments

Value

A list of class gt_equivalence_maximin.

Single-objective optimal approximate design (group testing)

Description

Solves a convex optimization problem over a finite candidate set for one criterion. The regression function f encodes rank-one contributions to the (approximate) information matrix, as in nonlinear design or group testing Fisher information assembled from pool outcomes.

Usage

compute_design_SO(
  u,
  f,
  criterion = c("D", "A", "Ds", "c", "E"),
  opts = list(),
  info_weight = NULL,
  solver = "CLARABEL",
  ...,
  support_tol = 1e-04,
  drop_tol = 1e-08
)

Arguments

Value

A list of class "gt_so_design" and "gt_design".

Maximin multi-criterion approximate design (group testing)

Description

Joint convex formulation for maximizing the minimum efficiency across several criteria, using reference losses from single-objective designs. Suitable when multiple experimental goals (e.g. overall prevalence versus contrasts) must be balanced in group testing allocation.

Usage

compute_maximin_design(
  u,
  f,
  loss_ref,
  criteria,
  opts = list(),
  info_weight = NULL,
  solver = "CLARABEL",
  ...,
  support_tol = 1e-04,
  drop_tol = 1e-08
)

Arguments

Details

Link to Yeh, Wong, and Zhou (arXiv:2508.08445, Sec. 4.1). Let \mathbf{M}(\mathbf{w})=\mathbf{I}(\mathbf{w},\theta^*) be the information matrix on the candidate set, and let \phi_D,\phi_A,\phi_c,\phi_E be the single-objective functionals in their eq. (4), with efficiencies \mathrm{Eff}_j(\mathbf{w}) in eq. (5).

• Eq. (6) — Maximin objective:

  \max_{\mathbf{w}\in\Delta_M}\ \min\{\mathrm{Eff}_1(\mathbf{w}),\ldots,\mathrm{Eff}_K(\mathbf{w})\}.

  At the optimum, \min_j \mathrm{Eff}_j = 1/t^* for the scalar t^* below (paper’s t).

• Eq. (7) — Equivalent convex program (Gao et al., 2025):

  \min_{\mathbf{w},\,t\ge 0} t \quad\text{s.t.}\quad \Phi_j(\mathbf{w}) \le h_j(t),\ j=1,\ldots,K,

  where \Phi_j is \log\phi_D for D, \phi_A for A, \phi_c for c / Ds, and \phi_E for E, as in the paper. This function minimizes tstar (t in the paper).

• Eq. (8) — Bounds h_j(t) on the right-hand side (with s=\dim(\theta)):

  h_D(t)=\log\phi_D(\mathbf{w}_D^*)+s\log t,\quad h_A(t)=t\,\phi_A(\mathbf{w}_A^*),\quad h_c(t)=t\,\phi_c(\mathbf{w}_c^*),\quad h_E(t)=\phi_E(\mathbf{w}_E^*)/t.

  Implemented constraints (same structure; build loss_ref from calc_Dopt(), calc_Aopt(), calc_copt(), calc_Eopt()):

  • D: -\log\det(\mathbf{M}) \le \mathrm{loss}_D^{\mathrm{ref}} + s\log(t^*) with \mathrm{loss}_D^{\mathrm{ref}} = -\log\det(\mathbf{M}_D^*).

  • A: \mathrm{tr}(\mathbf{M}^{-1}) \le t^*\,\mathrm{loss}_A^{\mathrm{ref}}.

  • c / Ds: \mathbf{c}^\top\mathbf{M}^{-1}\mathbf{c} \le t^*\,\mathrm{loss}^{\mathrm{ref}}.

  • E: -\lambda_{\min}(\mathbf{M}) \le \mathrm{loss}_E^{\mathrm{ref}}/t^* with \mathrm{loss}_E^{\mathrm{ref}} = -\lambda_{\min}(\mathbf{M}_E^*) as from calc_Eopt().

Reference losses must match the paper’s \phi-scale and the same conventions as compute_design_SO() (internal scalar loss).

Value

A list of class "gt_maximin_design" and "gt_design".

References

Yeh, C.-K., Wong, W. K., Zhou, J. (2025). Single and multi-objective optimal designs for group testing experiments. arXiv 2508.08445. Sec. 4.1, eq. (6)–(8).

Efficiencies of an exact design relative to single-objective optima (maximin)

Description

Computes criterion-wise efficiencies as in eq. (5) of Yeh, Wong, and Zhou (arXiv:2508.08445), and their minimum (MinEff in Table 4). Use after round_gt_design_budget() with a maximin approximate design: pass M_exact = out$M_exact, the same loss_ref as in compute_maximin_design(), and the same criteria vector.

Usage

exact_design_efficiency_maximin(
  M_exact,
  loss_ref,
  criteria,
  opts = list(),
  p = nrow(M_exact)
)

Arguments

Value

A list with efficiencies (named numeric vector) and min_efficiency (\min_j \mathrm{Eff}_j).

Standardized cost for pool size (Huang et al. 2020)

Description

c(x) = 1 - q + q x

with q = q_1 / (q_0 + q_1) for assay cost q_0 and enrollment cost q_1. Value q = 0 gives c(x) \equiv 1.

Usage

gt_huang2020_cost(x, q)

Arguments

Value

Scalar cost.

Gradient vector \mathbf{f}(x) for the Huang et al. (2020) model

Description

Partial derivatives of \pi(x\mid\theta) with respect to (p_0,p_1,p_2) as in arXiv:2508.08445 (Eq. below their Eq. (1)).

Usage

gt_huang2020_f(x, theta)

Arguments

Value

Length-3 numeric vector.

Weight \lambda(x) in the information matrix (Huang et al. 2020)

Description

\lambda(x) = [c(x)\,\pi(x)\{1-\pi(x)\}]^{-1}

Usage

gt_huang2020_lambda(x, theta, q)

Arguments

Value

Scalar (positive when \pi is interior).

Positive test probability (Huang et al. 2020 / arXiv:2508.08445 Sec. 2)

Description

\pi(x \mid \theta) = p_1 - (p_1 + p_2 - 1)(1 - p_0)^x

Usage

gt_huang2020_pi(x, theta)

Arguments

Value

Scalar probability in ⁠(0, 1)⁠ when well-defined.

Effective regressor \sqrt{\lambda(x)}\,\mathbf{f}(x) for convex design code

Description

The information matrix in Huang et al. (2020) is \sum_i w_i \lambda(x_i) \mathbf{f}(x_i)\mathbf{f}(x_i)^\top. The same matrix equals \sum_i w_i \mathbf{h}(x_i)\mathbf{h}(x_i)^\top with \mathbf{h}(x)=\sqrt{\lambda(x)}\mathbf{f}(x), which matches the regression form used by calc_Dopt() and check_equivalence() without an info_weight argument.

Usage

gt_huang2020_regressor(theta, q = 0)

Arguments

Value

A function ⁠function(x)⁠ returning a length-3 vector.

References

Yeh, C.-K., Wong, W. K., and Zhou, J. (2025). Single and multi-objective optimal designs for group testing experiments. arXiv:2508.08445.

Huang, S.-Y., Chen, Y.-H., and Wang, W. (2020). Optimal group testing designs for estimating prevalence with imperfect tests. Journal of the Royal Statistical Society Series C.

Maximin design with reference losses, equivalence, and eta (workflow)

Description

Runs the usual multi-step maximin pipeline: single-objective designs to build loss_ref, compute_maximin_design(), calc_directional_derivatives(), calc_eta_weights_maximin(), and optionally check_equivalence_maximin().

Usage

maximin_design_workflow(
  u,
  f,
  criteria,
  opts = list(),
  drop_tol = 1e-06,
  q = NULL,
  tol_eta = 0.001,
  tol_equiv = 0.002,
  check_equiv = TRUE,
  keep_reference_designs = FALSE,
  info_weight = NULL,
  solver = "CLARABEL",
  eta_args = list(),
  deriv_args = list(),
  make_figure = FALSE,
  plot_args = list(),
  ...
)

Arguments

Details

Only criteria D, A, and c are supported end-to-end (directional derivatives for Ds / E are not wired here). For c, supply opts = list(cVec_c = ...) as in compute_maximin_design().

Value

A list with components: loss_ref, maximin (output of compute_maximin_design()), directional_derivatives, eta, equivalence (or NULL if check_equiv is FALSE), q, and optionally reference_designs. Plotting is a side effect when make_figure is TRUE.

Plot equivalence theorem directional derivative

Description

Plot equivalence theorem directional derivative

Usage

plot_equivalence(
  eq_obj,
  main = NULL,
  xlab = "Design point",
  ylab = "Directional derivative",
  pch_support = 19,
  ...
)

Arguments

Value

Invisibly returns eq_obj.

Plot equivalence diagnostics for a maximin design

Description

Plot equivalence diagnostics for a maximin design

Usage

plot_equivalence_maximin(
  design_obj,
  directional_derivatives,
  eta,
  criteria = NULL,
  main_prefix = NULL,
  line_width = 2,
  show_support = TRUE,
  tol = 1e-06,
  cex_lab = 1.2,
  cex_axis = 1,
  cex_main = 1.1,
  mar = c(5, 6.5, 3, 1)
)

Arguments

Value

Invisibly returns the object produced by check_equivalence_maximin().

Exact group-testing design under a fixed budget (Rounding Algorithm II)

Description

Implements the floor allocation, zero-fix, extended-support search, and best-merge steps in Sec. 5.1 of Yeh, Wong, and Zhou (arXiv:2508.08445), as in the reference MATLAB scripts GT_Single_budget.m / calc_budget_round_combinations.m.

Usage

round_gt_design_budget(
  approx_design,
  u,
  theta,
  C,
  q_cost,
  criterion = c("D", "A", "c", "Ds", "E"),
  opts = list(),
  n_index = 2L,
  fix_zero_floor = TRUE,
  repair_floor_budget = TRUE,
  ...
)

Arguments

Value

A list with design_round1 (2-row matrix: pool sizes, floor counts; columns with zero runs are removed; no column names), design_exact (same format after merge), delta (2-row matrix: pool sizes x and Delta_n = n_{\mathrm{exact}} - n_{\mathrm{round1}}; only pool sizes with nonzero change are columns), M_approx, M_exact, efficiency, loss_approx, loss_exact, C_remaining after the floor step (with default repair_floor_budget, total cost is at most C): \max\{0, \mathrm{round}(C - \sum_i n_i c(x_i), 4)\} (never negative), extension_table (tibble::tibble() of tight extensions; first columns named by extended-support pool sizes, then used_cost, remaining, loss when present), and criterion.

Exact maximin design under fixed budget (Algorithm II + search)

Description

Applies cost-aware floor rounding, then modified Step II search over nearby support points (x_i \pm n_index) and selects the extension with the largest minimum efficiency (MinEff) across criteria.

Usage

round_gt_design_budget_maximin(
  approx_design,
  u,
  theta,
  C,
  q_cost,
  loss_ref,
  criteria,
  opts = list(),
  n_index = 2L,
  fix_zero_floor = TRUE,
  repair_floor_budget = TRUE,
  ...
)

Arguments

Value

A list with design_round1, design_exact, delta, M_round1, M_exact, efficiencies, min_efficiency, C_remaining after floor, and extension_table (tibble sorted by decreasing min_efficiency).

Exact maximin design under fixed run size (Algorithm I + search)

Description

Rounds a maximin approximate design to an exact design with total run size n, then applies the modified Step II search over nearby support points (x_i \pm n_index) and selects the extension with the largest minimum efficiency (MinEff) across criteria.

Usage

round_gt_design_n_maximin(
  approx_design,
  u,
  theta,
  n,
  q_cost,
  loss_ref,
  criteria,
  opts = list(),
  n_index = 2L,
  ...
)

Arguments

Value

A list with design_round1, design_exact, delta, M_round1, M_exact, efficiencies (named vector), min_efficiency, and extension_table (tibble sorted by decreasing min_efficiency).

Exact design under subject-count constraint via budget rounding

Description

Converts a subject cap (n_subject_allow) into a test budget C_tests = floor(n_subject_allow / sum(w_i x_i)) using the approximate design, runs round_gt_design_budget(), then selects the best rounded extension under the subject-count constraint.

Usage

round_gt_design_subject_budget(
  approx_design,
  u,
  theta,
  n_subject_allow,
  q_cost,
  criterion = c("D", "A", "c", "Ds", "E"),
  opts = list(),
  n_index = 2L,
  fix_zero_floor = TRUE,
  repair_floor_budget = TRUE,
  ...
)

Arguments

Details

Selection rule follows the application script logic: among feasible candidates (subjects <= n_subject_allow), prefer using more subjects (closest to the cap), then smaller loss. If none are feasible, pick the minimum-excess candidate.

Value

A list with C_tests, n_subject_allow, n_subjects_used, design_round1, design_exact, delta, M_approx, M_exact, loss_approx, loss_exact, efficiency, criterion, and extension_table.

Enumerate budget-feasible integer allocations (cost-aware rounding)

Description

All nonnegative integer vectors \Delta with \Delta^\top c \le C_r, then restricted to tight rows where remaining budget is insufficient for any additional unit at minimum cost (Step II in Rounding Algorithm II, arXiv:2508.08445, Sec. 5.1).

Usage

rounding_budget_combinations(cxx, Cr)

Arguments

Value

Matrix whose first length(cxx) columns are counts, then used cost, then remaining budget. Sorted like the MATLAB reference implementation.

Enumerate nonnegative integer allocations (run-size rounding)

Description

All vectors (z_1,\ldots,z_m) with z_j \ge 0, \sum_j z_j \le max_run_size, matching the supplementary Rounding Algorithm I search (arXiv:2508.08445, Sec. 5.1).

Usage

rounding_run_size_combinations(n_items, max_run_size)

Arguments

Value

Numeric matrix with columns z_1,\ldots,z_m, then total count, then remaining slots (⁠max_run_size -⁠ total), sorted lexicographically with the last coordinate changing fastest (MATLAB sortrows order).