simPower.RdCalculates simulated power for a prespecified sample size.
The outcome family is selected through distribution, matching the
unified sampleSize() interface.
simPower(
n,
distribution = c("norm", "lnorm", "pois", "nbinom"),
mu_list = NULL,
varcov_list = NA,
sigma_list = NA,
cor_mat = NA,
sigmaB = 0,
rate_list = NULL,
exposure = 1,
dispersion = 0.1,
Eper = c(0, 0),
Eco = c(0, 0),
rho = 0,
TAR = NULL,
arm_names = NA,
ynames_list = NA,
type_y = NA,
list_comparator = NA,
list_y_comparator = NA,
alpha = 0.05,
lequi.tol = NA,
uequi.tol = NA,
list_lequi.tol = NA,
list_uequi.tol = NA,
dtype = "parallel",
ctype = "ROM",
vareq = TRUE,
k = NA,
adjust = "no",
dropout = NA,
nsim = 5000,
seed = 1234,
ncores = 1,
keep_sim_data = FALSE,
.warn_redundant_bon = TRUE
)Integer sample size or vector of sample sizes used for the simulation. For parallel studies this is the base sample size used to derive arm sizes; for 2x2 studies it is the number per sequence. A vector returns a simpower_curve object and enables plotting power across base sample sizes.
Outcome distribution using R's names: "norm",
"lnorm", "pois", or "nbinom" (case-insensitive). Longer labels
such as "normal", "lognormal", and "poisson" are also accepted.
Named list of continuous-outcome means per arm.
Optional list of covariance matrices for continuous outcomes.
Optional list of standard-deviation vectors for continuous outcomes.
Optional endpoint correlation matrix. For count outcomes, this is also the endpoint correlation matrix used by the joint count engine.
Between-subject parameter for a 2x2 design.
Named arm-rate list for count outcomes.
Count exposure per subject. This can be a scalar or endpoint vector shared by arms, or a named list of arm-specific values.
Negative-binomial dispersion. The per-subject
negative-binomial size is 1 / dispersion; parallel-arm totals use size
n / dispersion. This can be a scalar or endpoint vector shared by arms,
or a named list of arm-specific values.
Period effects for a 2x2 design.
Carry-over effects for a 2x2 design.
Common endpoint correlation when cor_mat is not supplied.
Treatment allocation rates for continuous parallel designs.
Optional arm names.
Optional endpoint names by arm.
Endpoint hierarchy for sequential testing for continuous and
count outcomes. Use 1 for primary/co-primary and 2 for secondary
endpoints.
Named list of treatment-reference comparisons. Each
element must be c(test, reference); the first arm is the test arm and
the second arm is the reference arm.
Endpoint selections by comparison.
For count outcomes, the selected endpoints are used to define the count
multiplicity and the effective k; in a joint count analysis all
comparisons must currently use the same selected endpoint set.
One-sided significance level.
Common lower equivalence bound.
Common upper equivalence bound.
Comparator-specific lower bounds.
Comparator-specific upper bounds.
Trial design: "parallel" or "2x2".
Test type. Use "DOM" (difference of means) or "ROM"
(ratio of means) for Normal and Lognormal outcomes, and "RR"
(event-rate ratio) for Poisson and Negative Binomial outcomes.
Whether variances are assumed equal for continuous outcomes.
Number of endpoints required per comparison.
Multiplicity adjustment: "no" (none), "bon"
(Bonferroni across all selected endpoints), "sid" (Sidak), "k"
(the existing weak K-fold rule), "t" (Mielke's strong
k-out-of-m adjustment, using alpha / (m - k + 1); legacy "pc"
aliases are accepted), or
"seq" (sequential hierarchy).
Dropout proportions. For count 2x2 studies, supply two sequence-specific values.
Number of simulated trials.
Random seed.
Number of computation cores. For continuous outcomes this is passed to the compiled simulation backend; for count outcomes it splits Monte Carlo trials into independent seeded chunks whose C++ results are combined.
Logical. If TRUE, retain model-scale observations
for every simulated trial in sim_data for distribution diagnostics.
Defaults to FALSE because retained data can be large.
Logical. If TRUE, warn when a requested
multiplicity adjustment is redundant or uncalibrated.
An object containing estimated power and its 95% Monte Carlo
confidence interval. The unified function returns primary class simpower
for every distribution. If keep_sim_data = TRUE, the object also contains
long-format model-scale observations in sim_data. Count results additionally inherit from the
compatibility class countpower.
For Normal and Log Normal outcomes, supply the continuous-outcome inputs
(mu_list, sigma_list or varcov_list, and optionally cor_mat or
rho). For Poisson and Negative Binomial outcomes, supply rate_list,
list_comparator, list_lequi.tol, and list_uequi.tol. Count exposure
and dispersion may be scalar, endpoint-specific, or named arm-specific
lists. Arguments for the other outcome family are not used.
The returned object supports summary(), confint(), and plot().
The effective endpoint count is determined separately for each comparator
from list_y_comparator (or from the endpoints common to both arms when the
argument is omitted). k is checked against that count. The function warns
when an endpoint-wise adjustment is unnecessary because all selected
endpoints are required, and when adjust = "no" is used for a k < m
decision. type_y is used with adjust = "seq" for both continuous and
count outcomes; for other adjustments it is ignored with a warning.
For a k-of-m decision, adjust = "t" allocates alpha over the
m - k + 1 boundary endpoints relevant to the strong k-out-of-m null.
The legacy adjust = "pc" label is accepted as an alias.
Comparisons always use the order supplied in list_comparator: the first
arm is the test and the second arm is the reference. Thus, c("T", "R")
gives T - R for DOM, T / R for ROM, and the event-rate ratio
rate_T / rate_R for RR. Reversing the two names reverses the estimand.
For count outcomes, the estimand is the event-rate ratio lambda_T / lambda_R.
The equivalence hypotheses are H0: lambda_T / lambda_R <= L or
lambda_T / lambda_R >= U versus H1: L < lambda_T / lambda_R < U,
assessed by TOST. The same interval hypotheses apply to continuous mean
differences (DOM) or mean ratios (ROM), with the log-normal ROM analysis
performed on the log scale.
simPower(n = 100, distribution = "Poisson",
rate_list = list(TEST = .21, REF = .20),
list_comparator = list(TEST_vs_REF = c("TEST", "REF")),
list_lequi.tol = list(TEST_vs_REF = .80),
list_uequi.tol = list(TEST_vs_REF = 1.25),
exposure = 10, nsim = 100, seed = 1)
#> Fixed-sample-size power
#> Distribution: pois
#> Sample size: 100
#> Power: 0.4300 [0.3327, 0.5328]