Package {cmrdesign}

cmrdesign: Conditional Minimax Regret design rules

Description

Applied Conditional Minimax Regret (CMR) design rules for pilot-informed experiments. The package includes two-arm, shared-control multi-arm, stratified, multiple-outcome, proxy/delayed-outcome, unbounded-outcome, and pilot-planning workflows.

Author(s)

Maintainer: Juan C. Yamin juan_yamin_silva@brown.edu [copyright holder]

See Also

Useful links:

• https://juancyamin.github.io/cmrdesign/

• https://github.com/juancyamin/cmrdesign

• https://arxiv.org/abs/2607.16982

• Report bugs at https://github.com/juancyamin/cmrdesign/issues

Pilot-size activation thresholds

Description

Compute simple method-specific pilot-size activation thresholds for the Pilot-planning screen from Appendix E of the accompanying paper.

Usage

activation_threshold_bounded(
  alpha = 0.05,
  max_total_pilot = 10000L,
  min_arm_size = 2L
)

activation_threshold_bernoulli(alpha = 0.05)

Arguments

Value

Total pilot size threshold. activation_threshold_bounded() returns Inf if no even pilot size up to max_total_pilot clears the bounded-outcome activation condition. activation_threshold_bernoulli() returns 4; the exact Bernoulli screen activates at the minimal admissible pilot regardless of alpha, which is validated for interface consistency.

See Also

Other pilot planning: break_even_pilot_share(), pilot_plan(), pilot_viability_band()

Examples

activation_threshold_bounded(alpha = 0.05, max_total_pilot = 200)
activation_threshold_bernoulli(alpha = 0.05)

Baseline and comparator assignment rules

Description

Standalone benchmark assignment rules for comparing CMR against balance, feasible Neyman, and simple regularized Neyman variants.

Usage

assign_balance(n = 1L)

assign_multiarm_balance(arms)

assign_stratified_balance(strata_share)

assign_feasible_neyman(vhat1, vhat0)

assign_trimmed_neyman(vhat1, vhat0, trim = 0.1)

assign_additive_regularized_neyman(vhat1, vhat0, nu)

assign_exponential_regularized_neyman(
  vhat1,
  vhat0,
  tau,
  zero_guard = c("any", "both", "none")
)

Arguments

Value

Numeric assignment shares. Two-arm functions return treatment shares. assign_multiarm_balance() returns a named vector over all arms, including control "0". assign_stratified_balance() returns total assignment shares for treatment and control cells named like "1:A" and "0:A".

See Also

Other assignment helpers: multiarm_variance_objective(), realize_allocation(), stratified_variance_objective(), variance_objective()

Examples

assign_balance(3)
assign_feasible_neyman(0.12, 0.04)
assign_trimmed_neyman(0.12, 0.04, trim = 0.10)
assign_multiarm_balance(2)
assign_stratified_balance(c(A = 0.4, B = 0.6))

Two-arm CMR from a variance rectangle

Description

Compute the closed-form two-arm CMR allocation for a supplied confidence rectangle over treatment and control variances.

Usage

binary_rectangle_corners(rectangle)

binary_rectangle_regret(pi, rectangle, return_details = FALSE)

cmr_two_arm_from_rectangle(rectangle)

cmr_binary_from_rectangle(rectangle)

Arguments

Value

cmr_two_arm_from_rectangle() returns a list of class cmr_two_arm with pi, U_CMR, the input rectangle, rectangle corners, corner regrets, binding-corner diagnostics, and additional solver diagnostics. binary_rectangle_corners() returns the two least-favorable rectangle corners. binary_rectangle_regret() returns the worst regret at pi, or a detailed list when return_details = TRUE.

See Also

Other CMR rules: cmr_multiarm(), cmr_multiarm_from_rectangle(), cmr_multiple_outcomes(), cmr_proxy(), cmr_stratified(), cmr_stratified_from_rectangle(), cmr_two_arm(), cmr_unbounded(), cmr_unbounded_from_rectangle(), print.cmr_two_arm()

Other rectangle helpers: cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

rect <- c(v_l1 = 0.02, v_u1 = 0.12, v_l0 = 0.01, v_u0 = 0.08)
fit <- cmr_two_arm_from_rectangle(rect)
fit$pi
fit$U_CMR
binary_rectangle_regret(0.5, rect)

Break-even pilot share

Description

Compute the design-only break-even pilot share implied by treatment and control standard deviations.

Usage

break_even_pilot_share(sigma1, sigma0, input = c("sd", "variance"))

Arguments

Value

Numeric break-even share in ⁠[0, 0.5]⁠.

See Also

Other pilot planning: activation_threshold_bounded(), pilot_plan(), pilot_viability_band()

Examples

break_even_pilot_share(sigma1 = 0.35, sigma0 = 0.20)
break_even_pilot_share(sigma1 = 0.35^2, sigma0 = 0.20^2, input = "variance")

Shared-control multi-arm CMR assignment

Description

Estimate arm-specific variance confidence intervals from pilot data and return the shared-control multi-arm CMR assignment.

Usage

cmr_multiarm(
  y,
  arm,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  control_arm = 0,
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  na.rm = TRUE,
  tol = 1e-11,
  solver_control = list(),
  max_vertices = 65536L
)

Arguments

Value

A list of class cmr_multiarm with named assignment shares pi over all arms, CMR certificate U_CMR, confidence set, pilot summaries, endpoint error allocation, and diagnostics.

See Also

Other CMR rules: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_multiple_outcomes(), cmr_proxy(), cmr_stratified(), cmr_stratified_from_rectangle(), cmr_two_arm(), cmr_unbounded(), cmr_unbounded_from_rectangle(), print.cmr_two_arm()

Examples

set.seed(5)
arm <- rep(c(0, 1, 2), each = 20)
y <- c(rbeta(20, 4, 4), rbeta(20, 2, 6), rbeta(20, 5, 3))
cmr_multiarm(y, arm, method = "bounded")

Multi-arm CMR from a variance rectangle

Description

Compute a shared-control multi-arm CMR allocation from a supplied variance rectangle.

Usage

cmr_multiarm_from_rectangle(rectangle, control = list(), max_vertices = 65536L)

Arguments

Value

A list of class cmr_multiarm with named assignment shares pi, regret certificate U_CMR, checked rectangle, enumerated vertices, vertex regrets, binding vertices, and solver diagnostics. For collapsed or full rectangles, closed-form shortcuts are used.

See Also

Other CMR rules: binary_rectangle_corners(), cmr_multiarm(), cmr_multiple_outcomes(), cmr_proxy(), cmr_stratified(), cmr_stratified_from_rectangle(), cmr_two_arm(), cmr_unbounded(), cmr_unbounded_from_rectangle(), print.cmr_two_arm()

Other rectangle helpers: binary_rectangle_corners(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

rect <- c(
  v_l0 = 0.02, v_u0 = 0.08,
  v_l1 = 0.04, v_u1 = 0.12,
  v_l2 = 0.01, v_u2 = 0.07
)
cmr_multiarm_from_rectangle(rect)

Multiple-outcome CMR assignment

Description

Estimate an effective two-arm variance rectangle for multiple outcomes and return the CMR treatment share.

Usage

cmr_multiple_outcomes(
  y,
  d,
  weights = NULL,
  estimand = c("coprimary", "index"),
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

Arguments

Value

A list of class cmr_multiple_outcomes and cmr_two_arm with treatment share pi, CMR certificate U_CMR, effective confidence rectangle, pilot summaries, outcome weights, estimand metadata, endpoint error allocation, and diagnostics.

See Also

Other CMR rules: binary_rectangle_corners(), cmr_multiarm(), cmr_multiarm_from_rectangle(), cmr_proxy(), cmr_stratified(), cmr_stratified_from_rectangle(), cmr_two_arm(), cmr_unbounded(), cmr_unbounded_from_rectangle(), print.cmr_two_arm()

Examples

set.seed(10)
d <- rep(c(1, 0), each = 20)
y <- cbind(
  y1 = c(rbeta(20, 2, 6), rbeta(20, 4, 4)),
  y2 = c(rbeta(20, 5, 3), rbeta(20, 3, 5))
)
cmr_multiple_outcomes(y, d, weights = c(0.6, 0.4))

Proxy or delayed-outcome CMR assignment

Description

Estimate a proxy-outcome rectangle, widen it using the bridge radius zeta, and return the CMR treatment share for the primary-outcome design.

Usage

cmr_proxy(
  proxy_y,
  d,
  zeta,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

cmr_delayed_outcome(
  proxy_y,
  d,
  zeta,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

Arguments

Value

A list of class cmr_proxy and cmr_two_arm with treatment share pi, CMR certificate U_CMR, widened confidence rectangle, pilot summaries, zeta, bridge diagnostics, endpoint error allocation, and method metadata.

See Also

Other CMR rules: binary_rectangle_corners(), cmr_multiarm(), cmr_multiarm_from_rectangle(), cmr_multiple_outcomes(), cmr_stratified(), cmr_stratified_from_rectangle(), cmr_two_arm(), cmr_unbounded(), cmr_unbounded_from_rectangle(), print.cmr_two_arm()

Examples

set.seed(12)
d <- rep(c(1, 0), each = 30)
proxy_y <- c(rbeta(30, 2, 6), rbeta(30, 4, 4))
cmr_proxy(proxy_y, d, zeta = 0.05)

Stratified CMR assignment

Description

Estimate cell-specific variance confidence intervals from pilot data and return the stratified CMR assignment across treatment/control by stratum cells.

Usage

cmr_stratified(
  y,
  d,
  strata,
  strata_share,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  na.rm = TRUE,
  tol = 1e-11,
  solver_control = list(),
  max_vertices = 65536L
)

Arguments

Value

A list of class cmr_stratified with total cell assignment shares pi, matrix form pi_matrix, sampling and treatment margins, CMR certificate U_CMR, confidence set, pilot summaries, endpoint error allocation, and diagnostics.

See Also

Other CMR rules: binary_rectangle_corners(), cmr_multiarm(), cmr_multiarm_from_rectangle(), cmr_multiple_outcomes(), cmr_proxy(), cmr_stratified_from_rectangle(), cmr_two_arm(), cmr_unbounded(), cmr_unbounded_from_rectangle(), print.cmr_two_arm()

Examples

set.seed(7)
strata <- rep(c("A", "B"), each = 40)
d <- rep(rep(c(1, 0), each = 20), 2)
y <- c(rbeta(20, 2, 6), rbeta(20, 4, 4),
       rbeta(20, 5, 3), rbeta(20, 3, 5))
cmr_stratified(y, d, strata, strata_share = c(A = 0.45, B = 0.55))

Stratified CMR from a variance rectangle

Description

Compute a stratified CMR allocation from a supplied cell-level variance rectangle.

Usage

cmr_stratified_from_rectangle(
  rectangle,
  strata_share,
  control = list(),
  max_vertices = 65536L
)

Arguments

Value

A list of class cmr_stratified with assignment shares pi, pi_matrix, stratum sampling margins, within-stratum treatment margins, CMR certificate U_CMR, checked rectangle, vertex diagnostics, and solver diagnostics.

See Also

Other CMR rules: binary_rectangle_corners(), cmr_multiarm(), cmr_multiarm_from_rectangle(), cmr_multiple_outcomes(), cmr_proxy(), cmr_stratified(), cmr_two_arm(), cmr_unbounded(), cmr_unbounded_from_rectangle(), print.cmr_two_arm()

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

strata_share <- c(A = 0.4, B = 0.6)
rect <- list(
  lower = rbind(treatment = c(A = 0.01, B = 0.04),
                control = c(A = 0.02, B = 0.03)),
  upper = rbind(treatment = c(A = 0.08, B = 0.12),
                control = c(A = 0.09, B = 0.10))
)
cmr_stratified_from_rectangle(rect, strata_share)

Two-arm Conditional Minimax Regret assignment

Description

Estimate a finite-sample variance confidence rectangle from pilot data and return the two-arm Conditional Minimax Regret (CMR) assignment.

Usage

cmr_two_arm(
  y,
  d,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr", "unbounded", "unbounded_mom", "median_of_means",
    "mom"),
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  psi = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

cmr_binary(
  y,
  d,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr", "unbounded", "unbounded_mom", "median_of_means",
    "mom"),
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  psi = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

Arguments

Value

A list of class cmr_two_arm with treatment share pi, regret certificate U_CMR, confidence rectangle, pilot summaries, endpoint error allocation, and diagnostics. For Maurer–Pontil bounded-outcome fits, pilot$vhat contains raw Bessel sample variances and can exceed 0.25 in finite samples; use confidence_set$treatment$statistic$projected_vhat and confidence_set$control$statistic$projected_vhat for diagnostics that require unit-interval variances. The object has compact print() and summary() methods.

See Also

Other CMR rules: binary_rectangle_corners(), cmr_multiarm(), cmr_multiarm_from_rectangle(), cmr_multiple_outcomes(), cmr_proxy(), cmr_stratified(), cmr_stratified_from_rectangle(), cmr_unbounded(), cmr_unbounded_from_rectangle(), print.cmr_two_arm()

Examples

set.seed(1)
d <- rep(c(1, 0), each = 40)
y <- c(rbeta(40, 2, 6), rbeta(40, 4, 4))

fit <- cmr_two_arm(y, d, alpha = 0.05, method = "bounded")
fit
summary(fit)

Unbounded-outcome CMR assignment

Description

Estimate a median-of-means variance rectangle from raw pilot outcomes and return the unbounded-outcome CMR assignment.

Usage

cmr_unbounded(y, d, psi = NULL, alpha = 0.05, na.rm = TRUE)

Arguments

Value

A list of class cmr_unbounded and cmr_two_arm. If both one-arm bounds are active, the object contains pi, finite U_CMR, rectangle, pilot summaries, and diagnostics. If the pilot is inactive, the function returns balance (pi = 0.5) with U_CMR = Inf and diagnostics explaining the fallback.

See Also

Other CMR rules: binary_rectangle_corners(), cmr_multiarm(), cmr_multiarm_from_rectangle(), cmr_multiple_outcomes(), cmr_proxy(), cmr_stratified(), cmr_stratified_from_rectangle(), cmr_two_arm(), cmr_unbounded_from_rectangle(), print.cmr_two_arm()

Examples

set.seed(4)
d <- rep(c(1, 0), each = 1000)
y <- c(rnorm(1000, sd = 1.3), rnorm(1000, sd = 0.8))
cmr_unbounded(y, d, psi = 3)

Unbounded-outcome CMR from a variance rectangle

Description

Compute the closed-form two-arm CMR allocation for a supplied nonnegative variance rectangle for unbounded outcomes.

Usage

cmr_unbounded_from_rectangle(rectangle)

Arguments

Value

A list of class cmr_unbounded and cmr_two_arm with treatment share pi, CMR certificate U_CMR, rectangle, corner regrets, binding diagnostics, and method metadata.

See Also

Other CMR rules: binary_rectangle_corners(), cmr_multiarm(), cmr_multiarm_from_rectangle(), cmr_multiple_outcomes(), cmr_proxy(), cmr_stratified(), cmr_stratified_from_rectangle(), cmr_two_arm(), cmr_unbounded(), print.cmr_two_arm()

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

rect <- c(v_l1 = 0.5, v_u1 = 1.4, v_l0 = 0.2, v_u0 = 1.0)
cmr_unbounded_from_rectangle(rect)

Diagnostic metrics for CMR simulations

Description

Small helpers for checking rectangle coverage, certificate validity, boundary assignment, and realized variance gains in simulation or validation code.

Usage

coverage_indicator(rectangle, truth)

certificate_valid(pi, U, truth, tol = 1e-10)

boundary_indicator(pi, tol = 0)

boundary_rate(pi, tol = 0)

saving_vs_balance(pi, v1, v0)

share_of_oracle_gain(pi, v1, v0, tol = 1e-12)

Arguments

Value

coverage_indicator(), certificate_valid(), and boundary_indicator() return logical values. boundary_rate(), saving_vs_balance(), and share_of_oracle_gain() return numeric values.

Examples

rect <- c(v_l1 = 0.02, v_u1 = 0.12, v_l0 = 0.01, v_u0 = 0.08)
truth <- c(v1 = 0.09, v0 = 0.04)
fit <- cmr_two_arm_from_rectangle(rect)
coverage_indicator(rect, truth)
certificate_valid(fit$pi, fit$U_CMR, truth)
saving_vs_balance(fit$pi, truth["v1"], truth["v0"])

Folded-binomial distribution for Bernoulli sample variances

Description

Probability mass and tail probabilities for the folded count that determines the exact Bernoulli sample variance.

Usage

folded_binomial_pmf(v, m)

folded_binomial_tails(v, m)

Arguments

Value

folded_binomial_pmf() returns a named probability vector over folded counts ⁠0, ..., floor(m / 2)⁠. folded_binomial_tails() returns a list with lower and upper cumulative tail probabilities.

See Also

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

folded_binomial_pmf(v = 0.20, m = 8)
folded_binomial_tails(v = 0.20, m = 8)

Multi-arm variance objectives and Neyman allocation

Description

Helper functions for shared-control multi-arm variance objectives, oracle values, Neyman allocations, regret, and rectangle vertices.

Usage

multiarm_variance_objective(pi, variances)

multiarm_oracle_variance(variances)

assign_multiarm_neyman(variances)

multiarm_regret(pi, variances)

multiarm_rectangle_vertices(rectangle, max_vertices = 65536L)

Arguments

Value

Numeric objective/regret values, named assignment vectors, or a vertex matrix. assign_multiarm_neyman() returns total assignment shares over control and all treatment arms. multiarm_rectangle_vertices() returns one row per variance-rectangle vertex.

See Also

Other assignment helpers: assign_balance(), realize_allocation(), stratified_variance_objective(), variance_objective()

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

variances <- c("0" = 0.05, "1" = 0.10, "2" = 0.04)
pi <- assign_multiarm_neyman(variances)
multiarm_variance_objective(pi, variances)
multiarm_regret(pi, variances)

Pilot/main-wave planning summary

Description

Summarize the pilot-size viability band and a default pilot-size suggestion.

Usage

pilot_plan(
  n,
  sigma1,
  sigma0,
  alpha = 0.05,
  method = c("bounded", "bernoulli"),
  input = c("sd", "variance"),
  accounting = c("design_only", "pooled"),
  desired_pilot = NULL,
  strict_upper = TRUE
)

cmr_plan(
  n,
  sigma1,
  sigma0,
  alpha = 0.05,
  method = c("bounded", "bernoulli"),
  input = c("sd", "variance"),
  accounting = c("design_only", "pooled"),
  desired_pilot = NULL,
  strict_upper = TRUE
)

Arguments

Value

A list of class cmr_pilot_plan with band, suggested_pilot, default_two_thirds_power, desired_pilot, desired_status, a text recommendation, and a caveat that the screen is necessary rather than sufficient.

See Also

Other pilot planning: activation_threshold_bounded(), break_even_pilot_share(), pilot_viability_band()

Examples

cmr_plan(
  n = 3000,
  sigma1 = 0.18,
  sigma0 = 0.28,
  desired_pilot = 120
)

Pilot viability band

Description

Compute a necessary viability screen for pilot sizes before choosing a pilot/main-wave split.

Usage

pilot_viability_band(
  n,
  sigma1,
  sigma0,
  alpha = 0.05,
  method = c("bounded", "bernoulli"),
  input = c("sd", "variance"),
  accounting = c("design_only", "pooled"),
  strict_upper = TRUE
)

Arguments

Value

A list of class cmr_pilot_viability_band with total sample size, standard deviations, method, break-even share and total, activation threshold, feasible even pilot sizes, and min/max feasible pilot sizes.

See Also

Other pilot planning: activation_threshold_bounded(), break_even_pilot_share(), pilot_plan()

Examples

pilot_viability_band(n = 3000, sigma1 = 0.18, sigma0 = 0.28)

Print and summarize CMR results

Description

Compact display methods for CMR result objects. These methods show the allocation, CMR certificate, method, sample size, and status without dumping nested confidence-set internals.

Usage

## S3 method for class 'cmr_two_arm'
print(x, ...)

## S3 method for class 'cmr_unbounded'
print(x, ...)

## S3 method for class 'cmr_proxy'
print(x, ...)

## S3 method for class 'cmr_multiple_outcomes'
print(x, ...)

## S3 method for class 'cmr_multiarm'
print(x, ...)

## S3 method for class 'cmr_stratified'
print(x, ...)

## S3 method for class 'cmr_two_arm'
summary(object, ...)

## S3 method for class 'cmr_unbounded'
summary(object, ...)

## S3 method for class 'cmr_proxy'
summary(object, ...)

## S3 method for class 'cmr_multiple_outcomes'
summary(object, ...)

## S3 method for class 'cmr_multiarm'
summary(object, ...)

## S3 method for class 'cmr_stratified'
summary(object, ...)

## S3 method for class 'summary.cmr_result'
print(x, ...)

Arguments

Value

print() methods return the original object invisibly. summary() methods return a compact list of class summary.cmr_result.

See Also

Other CMR rules: binary_rectangle_corners(), cmr_multiarm(), cmr_multiarm_from_rectangle(), cmr_multiple_outcomes(), cmr_proxy(), cmr_stratified(), cmr_stratified_from_rectangle(), cmr_two_arm(), cmr_unbounded(), cmr_unbounded_from_rectangle()

Examples

set.seed(13)
d <- rep(c(1, 0), each = 20)
y <- c(rbeta(20, 2, 6), rbeta(20, 4, 4))
fit <- cmr_two_arm(y, d)
print(fit)
summary(fit)

Convert CMR target shares to integer allocation counts

Description

Convert the continuous assignment shares returned by a CMR rule into executable integer counts for a main-wave sample. Counts are rounded by the deterministic largest-remainder rule. When x is a CMR result object, realize_allocation() also recomputes the regret certificate at the realized integer shares whenever the result contains enough rectangle information.

Usage

realize_allocation(
  x,
  n_main = NULL,
  strata_counts = NULL,
  min_per_arm = 1L,
  max_vertices = 65536L
)

## S3 method for class 'cmr_allocation'
print(x, ...)

Arguments

Value

A list of class cmr_allocation with integer counts, realized shares, realized pi, normalized target_pi, total n_main, rounding metadata, continuous and realized CMR certificates when available, and diagnostics. The diagnostics field certificate_recomputed is TRUE only when a realized certificate was recomputed from rectangle information.

See Also

Other assignment helpers: assign_balance(), multiarm_variance_objective(), stratified_variance_objective(), variance_objective()

Examples

set.seed(21)
d <- rep(c(1, 0), each = 40)
y <- c(rbeta(40, 2, 6), rbeta(40, 4, 4))
fit <- cmr_two_arm(y, d)
realize_allocation(fit, n_main = 101)

realize_allocation(c("0" = 0.34, "1" = 0.33, "2" = 0.33), n_main = 10,
                   min_per_arm = 0)

Two-arm confidence rectangles

Description

Construct a two-arm variance confidence rectangle from pilot data. These are expert helpers used by cmr_two_arm() and related extension functions.

Usage

rectangle_bernoulli_binary(
  y,
  d,
  alpha = 0.05,
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  na.rm = TRUE,
  tol = 1e-11
)

rectangle_binary(
  y,
  d,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr", "unbounded", "unbounded_mom", "median_of_means",
    "mom"),
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  psi = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

rectangle_two_arm(
  y,
  d,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr", "unbounded", "unbounded_mom", "median_of_means",
    "mom"),
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  psi = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

rectangle_bernoulli_two_arm(
  y,
  d,
  alpha = 0.05,
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  na.rm = TRUE,
  tol = 1e-11
)

Arguments

Value

A rectangle object. Bounded and Bernoulli methods return a cmr_binary_rectangle; unbounded methods return a cmr_unbounded_rectangle. The object contains the numeric rectangle, one-arm bound details, endpoint error allocation, pilot sample sizes and variance estimates, and method metadata.

See Also

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

d <- rep(c(1, 0), each = 6)
y <- c(1, 0, 1, 1, 0, 1, 0, 0, 1, 0, 0, 1)
rectangle_two_arm(y, d, method = "bernoulli")
rectangle_binary(y, d, method = "auto")

Bounded two-arm confidence rectangle

Description

Construct a two-arm variance confidence rectangle for bounded outcomes using Maurer–Pontil or Martinez-Taboada–Ramdas one-arm bounds.

Usage

rectangle_bounded_two_arm(
  y,
  d,
  alpha = 0.05,
  method = c("bounded", "maurer_pontil", "mp", "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  na.rm = TRUE
)

rectangle_bounded_binary(
  y,
  d,
  alpha = 0.05,
  method = c("bounded", "maurer_pontil", "mp", "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  na.rm = TRUE
)

Arguments

Value

A cmr_binary_rectangle list with rectangle, one-arm bound objects for treatment and control, endpoint error allocation, sample sizes, pilot variance estimates, normalization details, and method metadata. For Maurer–Pontil bounds, the top-level vhat entries are raw Bessel sample variances and can exceed 0.25; the projected unit-interval values are in treatment$statistic$projected_vhat and control$statistic$projected_vhat.

See Also

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

d <- rep(c(1, 0), each = 5)
y <- c(0.20, 0.40, 0.30, 0.10, 0.60, 0.50, 0.30, 0.20, 0.40, 0.10)
rectangle_bounded_binary(y, d, method = "bounded")

Multi-arm confidence rectangle

Description

Construct arm-specific variance confidence intervals for a shared-control multi-arm design.

Usage

rectangle_multiarm(
  y,
  arm,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  control_arm = 0,
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

Arguments

Value

A list of class cmr_multiarm_rectangle with checked rectangle, arm labels, one-arm bound results, endpoint error allocation, sample sizes, pilot variance estimates, normalization details, and method metadata.

See Also

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

set.seed(6)
arm <- rep(c(0, 1, 2), each = 12)
y <- c(rbeta(12, 4, 4), rbeta(12, 2, 6), rbeta(12, 5, 3))
rectangle_multiarm(y, arm, method = "bounded")

Multiple-outcome confidence rectangle

Description

Construct an effective two-arm variance rectangle for multiple outcomes. For estimand = "index", outcomes are first combined using weights. For estimand = "coprimary", one rectangle is built per outcome and combined conservatively using the outcome weights.

Usage

rectangle_multiple_outcomes(
  y,
  d,
  weights = NULL,
  estimand = c("coprimary", "index"),
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

Arguments

Value

A list of class cmr_multiple_outcomes_rectangle. For estimand = "index", this wraps the ordinary two-arm rectangle for the weighted index. For estimand = "coprimary", it contains the effective two-arm rectangle, weights, outcome-specific bounds, pilot summaries, endpoint error allocation, and method metadata.

See Also

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

set.seed(9)
d <- rep(c(1, 0), each = 20)
y <- cbind(
  y1 = c(rbeta(20, 2, 6), rbeta(20, 4, 4)),
  y2 = c(rbeta(20, 5, 3), rbeta(20, 3, 5))
)
rectangle_multiple_outcomes(y, d, weights = c(0.6, 0.4))

Proxy or delayed-outcome confidence rectangle

Description

Construct a primary-outcome variance rectangle by estimating a proxy-outcome rectangle and widening each arm's standard-deviation interval by zeta.

Usage

rectangle_proxy(
  proxy_y,
  d,
  zeta,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

rectangle_delayed_outcome(
  proxy_y,
  d,
  zeta,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  correction = c("bonferroni", "sidak_arms"),
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

Arguments

Value

A list of class cmr_proxy_rectangle and cmr_binary_rectangle with the widened primary-outcome rectangle, the underlying proxy confidence set, zeta, bridge metadata, endpoint error allocation, pilot summaries, and method metadata.

See Also

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

set.seed(11)
d <- rep(c(1, 0), each = 30)
proxy_y <- c(rbeta(30, 2, 6), rbeta(30, 4, 4))
rectangle_proxy(proxy_y, d, zeta = 0.05)

Stratified confidence rectangle

Description

Construct cell-specific variance confidence intervals for a stratified two-arm design.

Usage

rectangle_stratified(
  y,
  d,
  strata,
  strata_share,
  alpha = 0.05,
  method = c("auto", "bounded", "bernoulli", "maurer_pontil", "mp", "bernoulli_exact",
    "martinez_taboada_ramdas", "mtr"),
  beta = NULL,
  normalize = FALSE,
  lower = NULL,
  upper = NULL,
  na.rm = TRUE,
  tol = 1e-11
)

Arguments

Value

A list of class cmr_stratified_rectangle with lower and upper rectangle matrices, checked rectangle details, stratum shares, cell-level one-arm bound results, endpoint error allocation, sample sizes, pilot variance estimates, normalization details, and method metadata.

See Also

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

set.seed(8)
strata <- rep(c("A", "B"), each = 24)
d <- rep(rep(c(1, 0), each = 12), 2)
y <- c(rbeta(12, 2, 6), rbeta(12, 4, 4),
       rbeta(12, 5, 3), rbeta(12, 3, 5))
rectangle_stratified(y, d, strata, strata_share = c(A = 0.45, B = 0.55))

Unbounded-outcome confidence rectangle

Description

Construct a two-arm median-of-means variance rectangle for raw numeric outcomes under bounded-kurtosis inputs.

Usage

rectangle_unbounded(y, d, psi = NULL, alpha = 0.05, na.rm = TRUE)

Arguments

Value

A list of class cmr_unbounded_rectangle with rectangle when active, one-arm treatment and control bound objects, pilot summaries, block diagnostics, psi, and status. If either arm is inactive, rectangle is NULL and status explains why.

See Also

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

set.seed(3)
d <- rep(c(1, 0), each = 1000)
y <- c(rnorm(1000, sd = 1.3), rnorm(1000, sd = 0.8))
rectangle_unbounded(y, d, psi = 3)

Stratified variance objectives and Neyman allocation

Description

Helper functions for stratified two-arm variance objectives, oracle values, Neyman allocations, regret, and rectangle vertices.

Usage

stratified_variance_objective(pi, variances, strata_share)

stratified_oracle_variance(variances, strata_share)

assign_stratified_neyman(variances, strata_share)

stratified_regret(pi, variances, strata_share)

stratified_rectangle_vertices(rectangle, strata_share, max_vertices = 65536L)

Arguments

Value

Numeric objective/regret values, named assignment vectors, or a vertex matrix. assign_stratified_neyman() returns total assignment shares over treatment/control by stratum cells.

See Also

Other assignment helpers: assign_balance(), multiarm_variance_objective(), realize_allocation(), variance_objective()

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

strata_share <- c(A = 0.4, B = 0.6)
variances <- rbind(
  treatment = c(A = 0.10, B = 0.04),
  control = c(A = 0.05, B = 0.08)
)
pi <- assign_stratified_neyman(variances, strata_share)
stratified_variance_objective(pi, variances, strata_share)

Exact Bernoulli variance bounds

Description

Exact one-arm variance confidence bounds for Bernoulli outcomes using the folded-binomial distribution of the sample variance.

Usage

variance_bounds_bernoulli_exact(y, beta_l, beta_u, na.rm = TRUE, tol = 1e-11)

Arguments

Value

A list with lower bound L, upper bound U, folded-binomial variance estimate vhat, method name, sample size n, and folded-count details in statistic.

See Also

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_maurer_pontil(), variance_bounds_unbounded_mom()

Examples

y <- c(1, 0, 1, 1, 0, 0, 1, 0)
variance_bounds_bernoulli_exact(y, beta_l = 0.025, beta_u = 0.025)

Bounded-outcome variance bounds

Description

One-arm distribution-free variance confidence bounds for outcomes in ⁠[0, 1]⁠.

Usage

variance_bounds_maurer_pontil(y, beta_l, beta_u, na.rm = TRUE)

variance_bounds_martinez_taboada_ramdas(
  y,
  beta_l,
  beta_u,
  na.rm = TRUE,
  lower_alpha_split = 0.5,
  c1 = 0.5,
  c2 = 0.25^2,
  c3 = 0.25,
  c4 = 0.5,
  c5 = 2,
  cs = FALSE,
  tilde_cs = TRUE
)

Arguments

Value

A list with lower bound L, upper bound U, sample variance vhat, method name, arm sample size n, and method-specific statistic details. For Maurer–Pontil bounds, vhat is the raw Bessel sample variance and can slightly exceed 0.25 in finite samples even though the returned endpoints are capped to ⁠[0, 0.25]⁠; use statistic$projected_vhat for diagnostics that require a variance on the unit-interval scale.

See Also

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_unbounded_mom()

Examples

y <- c(0.10, 0.30, 0.40, 0.20, 0.70, 0.50)
variance_bounds_maurer_pontil(y, beta_l = 0.025, beta_u = 0.025)

Unbounded-outcome median-of-means variance bounds

Description

Compute one-arm median-of-means variance bounds for raw numeric outcomes under a bounded-kurtosis input psi.

Usage

variance_bounds_unbounded_mom(y, alpha = 0.05, psi = NULL, na.rm = TRUE)

Arguments

Value

A list with lower bound L, upper bound U, median-of-means variance estimate vhat, method name, sample size n, activation flag active, status string, and block-level statistic details. If the pilot is too small or the relative-error radius is too large, active = FALSE, L = NA, and U = Inf.

See Also

Other rectangle helpers: binary_rectangle_corners(), cmr_multiarm_from_rectangle(), cmr_stratified_from_rectangle(), cmr_unbounded_from_rectangle(), folded_binomial_pmf(), multiarm_variance_objective(), rectangle_bernoulli_binary(), rectangle_bounded_two_arm(), rectangle_multiarm(), rectangle_multiple_outcomes(), rectangle_proxy(), rectangle_stratified(), rectangle_unbounded(), stratified_variance_objective(), variance_bounds_bernoulli_exact(), variance_bounds_maurer_pontil()

Examples

set.seed(2)
y <- rnorm(2000, sd = 1.3)
variance_bounds_unbounded_mom(y, alpha = 0.05, psi = 3)

Two-arm variance objectives and Neyman allocation

Description

Helper functions for the two-arm variance objective, oracle variance, Neyman allocation, and regret. These are useful for checking CMR certificates and comparing CMR against oracle or feasible-Neyman benchmarks.

Usage

variance_objective(pi, v1, v0)

oracle_variance(v1, v0)

assign_neyman(v1, v0)

regret(pi, v1, v0)

Arguments

Value

Numeric vector after ordinary R recycling of pi, v1, and v0. variance_objective() returns v1 / pi + v0 / (1 - pi), oracle_variance() returns the Neyman-oracle value (sqrt(v1) + sqrt(v0))^2, assign_neyman() returns the treatment share, and regret() returns excess variance relative to the oracle.

See Also

Other assignment helpers: assign_balance(), multiarm_variance_objective(), realize_allocation(), stratified_variance_objective()

Examples

v1 <- 0.12
v0 <- 0.04
pi <- assign_neyman(v1, v0)
variance_objective(pi, v1, v0)
oracle_variance(v1, v0)
regret(0.5, v1, v0)