Estimate sample size for count-rate equivalence — sampleSize

Searches for the smallest number of subjects per arm whose simulated power reaches the target for a rate-ratio equivalence test.

sampleSize_count(
  power = 0.8,
  rate_test,
  rate_reference,
  exposure = 1,
  margin_lower = 0.8,
  margin_upper = 1.25,
  model = c("poisson", "negative-binomial"),
  dispersion = 0.1,
  alpha = 0.05,
  nsim = 5000,
  seed = NULL,
  lower = 2,
  upper = 500,
  design = c("parallel", "2x2"),
  k = NULL,
  endpoint_corr = NULL,
  type_y = NULL,
  adjust = c("none", "bonferroni", "sidak", "t", "pc", "partial-conjunction",
    "partial_conjunction", "sequential"),
  sigmaB = 0,
  Eper = c(0, 0),
  Eco = c(0, 0),
  dropout = c(0, 0),
  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 power.
rate_test: Event rate in the test arm.
rate_reference: Event rate in the reference arm.
exposure: Exposure per subject; a scalar or one value per endpoint.
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. The per-subject negative-binomial size is 1 / dispersion; parallel-arm totals use size n / dispersion.
alpha: One-sided significance level.
nsim: Number of simulated trials.
seed: Optional random seed.
lower: Minimum subjects per arm.
upper: Maximum subjects per arm.
design: Trial design: "parallel" or "2x2". In a crossover design, the returned sample size is per sequence.
k: Number of endpoints that must demonstrate equivalence. Defaults to all supplied endpoints.
endpoint_corr: Endpoint correlation matrix used by the Gaussian copula for multi-endpoint count simulations. The default is independence.
type_y: Numeric endpoint hierarchy used with adjust = "seq": 1 for primary/co-primary endpoints and 2 for secondary endpoints.
adjust: Multiplicity adjustment for endpoint-wise one-sided alpha: "none", "bonferroni", "sidak", "t", or "seq"/"sequential". The "t" option uses Mielke's strong k-out-of-m calibration alpha / (m - k + 1); legacy partial-conjunction labels are accepted.
sigmaB: Between-subject standard deviation for the count 2x2 design.
Eper: Period effects for the count 2x2 design.
Eco: Carry-over effects for the count 2x2 design.
dropout: Dropout proportions for the count 2x2 design.
optimization_method: Search method. "fast" brackets the power crossing and uses integer bisection; "step-by-step" evaluates every candidate sample size.
step.power: Initial power-of-two jump used by the fast search.
step.up: Direction of the initial bracketing search.
pos.side: Retained for compatibility with sampleSize(); count searches 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 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. 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.

Examples

SimTOST:::sampleSize_count(0.80, 0.20, 0.20, lower = 100, upper = 2000,
                 nsim = 100, seed = 1)
#> Count-rate equivalence sample size
#> Subjects per arm: 1691 
#> Total subjects: 3382 
#> Endpoints: 1 (required: 1 )
#> Alpha adjustment: none 
#> Achieved power: 0.8000 [0.7057, 0.8708]