Estimate sample size for joint correlated count equivalence

sampleSize_count_joint(
  power = 0.8,
  rates,
  comparisons,
  exposure = 1,
  margin_lower = 0.8,
  margin_upper = 1.25,
  model = c("poisson", "negative-binomial"),
  dispersion = 0.1,
  alpha = 0.05,
  endpoint_corr = NULL,
  k = NULL,
  type_y = NULL,
  adjust = c("none", "bonferroni", "sidak", "t", "pc", "partial-conjunction",
    "partial_conjunction", "sequential"),
  nsim = 5000,
  seed = NULL,
  lower = 2,
  upper = 500,
  design = c("parallel"),
  list_margin_lower = NULL,
  list_margin_upper = NULL,
  optimization_method = c("fast", "step-by-step"),
  step.power = 6,
  step.up = TRUE,
  pos.side = FALSE,
  maxiter = 1000,
  ncores = 1,
  .warn_redundant_bon = TRUE
)

Arguments

power: Target joint power.
rates: Named list of equal-length endpoint-rate vectors, one per arm.
comparisons: Named list of treatment-reference arm pairs.
exposure: Exposure per subject, scalar or one value per endpoint, or a named list with one scalar/vector per arm.
margin_lower: Lower rate-ratio equivalence margin.
margin_upper: Upper rate-ratio equivalence margin.
model: Count model: "poisson" or "negative-binomial".
dispersion: Positive negative-binomial dispersion parameter.
alpha: One-sided significance level.
endpoint_corr: Endpoint correlation matrix; the default is independence.
k: Number of endpoints that must pass within every comparison.
type_y: Numeric endpoint hierarchy used with adjust = "seq": 1 for primary/co-primary endpoints and 2 for secondary endpoints.
adjust: Multiplicity adjustment within each comparison's endpoint family.
nsim: Number of simulated trials.
seed: Optional random seed.
lower: Minimum subjects per arm.
upper: Maximum subjects per arm.
design: Joint multi-arm design; currently only "parallel" is supported.
list_margin_lower: Optional named list of lower margins, one vector per comparison.
list_margin_upper: Optional named list of upper margins, one vector per comparison.
optimization_method: Search method: "fast" uses bracketing and integer bisection; "step-by-step" evaluates every candidate.
step.power: Initial power-of-two jump for the fast search.
step.up: Direction of the initial fast-search bracketing.
pos.side: Retained for compatibility with sampleSize(); count searches always return the smallest candidate reaching the target.
maxiter: Maximum number of power evaluations.
ncores: Number of worker processes used for count simulations. Set to 1 for serial execution. Parallel execution splits nsim into reproducible independent chunks and combines the resulting successes.
.warn_redundant_bon: Logical. If TRUE, warn about redundant or uncalibrated multiplicity configurations.

Value

An object of class countss containing the selected sample size, achieved joint power, confidence interval, input parameters, and the search history in table.iter and table.test. For count outcomes, table.iter has one row per evaluated candidate sample size and table.test contains complete-trial, comparator, and endpoint decision indicators for each simulated trial and candidate. The count kernel returns aggregate decision counts rather than raw endpoint-level test statistics, so component columns preserve the simulated marginal success counts.