Estimate power for count-rate equivalence

.power_count_serial(
  n_per_arm,
  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,
  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),
  type_y_active = FALSE
)

Arguments

n_per_arm: Subjects per arm.
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 margin; a scalar or one value per endpoint.
margin_upper: Upper rate-ratio margin; a scalar or one value per endpoint.
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 simulations.
seed: Optional random seed.
design: Trial design: "parallel" or "2x2". For "2x2", n_per_arm is interpreted as subjects 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. Named vectors are recommended when endpoint names are available.
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. Sequential testing applies the same primary-gate/secondary-family rule as the continuous kernels. When k equals the number of supplied endpoints, endpoint-wise adjustment is not necessary for the all-endpoints-required intersection-union decision; the requested method is retained but a warning is issued.
sigmaB: Between-subject standard deviation on the log-rate scale for the count 2x2 design.
Eper: Numeric vector of length 2 containing period effects on the log-rate scale.
Eco: Numeric vector of length 2 containing carry-over effects on the log-rate scale, ordered as reference carry-over and treatment carry-over.
dropout: Numeric vector of length 2 containing dropout proportions for the two crossover sequences.
type_y_active: Internal flag indicating whether type_y is active.

Value

An object of class countpower containing estimated power and its binomial confidence interval.

Details

For design = "2x2", complete participants contribute one count under each treatment. The kernel analyzes within-participant log-rate contrasts, averages the two sequence-specific estimates to remove period effects, and applies the carry-over correction implied by Eco = c(reference_carryover, treatment_carryover). exposure is used as the log-rate offset. sigmaB is the standard deviation of a subject random intercept used in the count-generating model; it cancels from the within-participant treatment contrast. The standard error is estimated from the empirical variance of the subject-level contrasts. Participants who drop out before completing both periods do not contribute to this paired analysis.

Examples

SimTOST:::power_count(40, 0.20, 0.20, nsim = 100, seed = 1)
#> Count-rate equivalence power
#> Model: poisson 
#> Design: parallel 
#> Subjects per arm: 40 
#> Endpoints: 1 (required: 1 )
#> Alpha adjustment: none 
#> Power: 0.0000 [0.0000, 0.0461]