Package 'SimTOST'

Description

Shows the distribution of within-trial, within-arm endpoint correlations. The dashed line is the user-specified target correlation.

Usage

.plot_correlation(
  x,
  type = c("density", "histogram", "ecdf"),
  display = "all",
  endpoint = NULL,
  arm = NULL,
  show_reference = TRUE,
  max_points = 100000L,
  ...
)

Arguments

Value

A ggplot object.

Description

Each simulated trial contains all arms and endpoints. Endpoint counts are generated with their requested marginal Poisson or negative-binomial distributions and a Gaussian-copula dependence structure. Every comparison must pass at least k endpoints for the trial to count as a success.

Usage

.power_count_joint_serial(
  n_per_arm,
  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,
  design = c("parallel"),
  list_margin_lower = NULL,
  list_margin_upper = NULL,
  type_y_active = FALSE
)

Arguments

Value

An object of class countpower containing joint power and a binomial confidence interval.

Examples

rates <- list(TEST = c(.20, .20), REF = c(.20, .20), ALT = c(.20, .20))
SimTOST:::power_count_joint(100, rates, list(REF = c("TEST", "REF"),
                     ALT = c("TEST", "ALT")), nsim = 100, seed = 1)

Description

Estimate power for count-rate equivalence

Usage

.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

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.

Value

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

Examples

SimTOST:::power_count(40, 0.20, 0.20, nsim = 100, seed = 1)

Description

Preserve named-vector indexing for legacy Mielke examples

Usage

## S3 method for class 'simss_mielke'
x[i, ...]

Arguments

Description

Coerce a Mielke result to a numeric sample size

Usage

## S3 method for class 'simss_mielke'
as.numeric(x, ...)

Arguments

Description

Extract the Monte Carlo confidence interval from count power results

Usage

## S3 method for class 'countpower'
confint(object, parm = NULL, level = 0.95, ...)

## S3 method for class 'countss'
confint(object, parm = NULL, level = 0.95, ...)

Arguments

Value

A named vector containing the lower and upper interval limits.

Description

Extract the Monte Carlo confidence interval from fixed-sample-size power results

Usage

## S3 method for class 'simpower'
confint(object, parm, level = 0.95, ...)

Arguments

Value

A two-column matrix containing the lower and upper interval limits.

Description

Confidence Interval for Achieved Power from simss object

Usage

## S3 method for class 'simss'
confint(object, parm = NULL, level = 0.95, ...)

Arguments

Value

A named numeric vector with two elements:

Achieved Power

Achieved power.

Lower

Lower bound of the confidence interval.

Upper

Upper bound of the confidence interval.

Examples

## Not run: 
# confint(res), where res is returned by sampleSize()

## End(Not run)

Description

Constructs and returns a list of key parameters (mean vectors, variance-covariance matrices, and allocation rates) required for input into the sampleSize function. This function ensures that the parameters for each endpoint and comparator are consistent, properly named, and formatted.

Usage

get_par(
  mu_list,
  varcov_list,
  TAR_list,
  type_y = NA,
  arm_names = NA,
  y_names = NA
)

Arguments

Value

A named list with the following components:

mu

A list of mean vectors, named according to arm_names.

varcov

A list of variance-covariance matrices, named according to arm_names.

tar

A list of treatment allocation rates (TARs), named according to arm_names.

type_y

A vector specifying the type of each endpoint.

weight_seq

A weight sequence calculated from type_y, used for endpoint weighting.

y_names

A vector of names for the endpoints, named as per y_names.

#' @details This function ensures that all input parameters (mu_list, varcov_list, and TAR_list) are consistent across comparators and endpoints. It performs checks for positive semi-definiteness of variance-covariance matrices and automatically assigns default names for arms and endpoints if not provided.

Examples

mu_list <- list(c(0.1, 0.2), c(0.15, 0.25))
varcov_list <- list(matrix(c(1, 0.5, 0.5, 1), ncol = 2), matrix(c(1, 0.3, 0.3, 1), ncol = 2))
TAR_list <- list(0.5, 0.5)
get_par(mu_list, varcov_list, TAR_list, type_y = c(1, 2), arm_names = c("Arm1", "Arm2"))

Description

Shows the equivalence decision (pass or fail) for every endpoint and comparator in every simulated trial. Each tile is one binary decision; green means that the criterion passed and orange means that it failed. The Total row is the combined decision for the comparator, and an ⁠All comparators⁠ panel, when present, shows the overall decision. This makes isolated failures, unstable endpoints, and systematic comparator differences easy to identify.

Usage

plot_decision_heatmap(x, display = "all", ...)

Arguments

Details

The x-axis is the simulation-trial number and has no scientific meaning beyond showing the sequence of simulated datasets. Endpoint rows show individual decisions; Total shows the combined endpoint decision according to k and the specified decision rule. The heatmap is a diagnostic of trial-level decisions, not a replacement for the numerical power estimate.

Value

A ggplot object.

Description

Creates density, histogram, ECDF, or Q–Q plots for a selected trial-level quantity. The estimand argument selects an arm parameter, a reconstructed TOST statistic, a continuous comparison, a count rate ratio, or endpoint correlations.

Usage

plot_distribution(x, estimand = "mu", arms = NULL, endpoints = NULL, ...)

Arguments

Details

Every comparator follows the package convention c(test, reference). For t_value, the lower and upper TOST statistics are reconstructed from the retained outcomes using the same continuous parallel formulas as the test. The dashed lines are the corresponding one-sided critical values. The plotted DOM is test - reference and the plotted ROM is test / reference; reversing the comparator reverses the displayed estimand. The plotted RR is rate_test / rate_reference.

Value

A ggplot object.

Description

Displays the 95\ of simulated trials increases. Decreasing curves indicate improving precision; a curve that has not flattened may require a larger nsim.

Usage

plot_mc_error(x, display = "all", overall = FALSE, endpoint = "Total", ...)

Arguments

Value

A ggplot object.

Description

Displays cumulative achieved power over simulated trials. A stable curve approaches a horizontal plateau, while large late movements indicate that more simulations may be needed.

Usage

plot_stability(
  x,
  target_power = 0.8,
  display = "all",
  overall = FALSE,
  endpoint = "Total",
  ...
)

Arguments

Value

A ggplot object.

Description

Plot count-outcome power results

Usage

## S3 method for class 'countpower'
plot(x, target_power = 0.8, ...)

Arguments

Value

A ggplot object showing estimated power and its Monte Carlo confidence interval. The interval is shown as a clearly visible vertical line through each point.

Description

Plot count-outcome sample-size results

Usage

## S3 method for class 'countss'
plot(x, target_power = 0.8, display = "all", all = TRUE, endpoint = NULL, ...)

Arguments

Value

A ggplot object showing the simulated power curve over the evaluated candidate sample sizes, with the selected sample size highlighted. Confidence intervals are shown as clearly visible vertical lines through each point. If an older countss object has no search history, the plot falls back to the selected-sample-size point.

Description

Plot fixed-sample-size power results

Usage

## S3 method for class 'simpower'
plot(x, target_power = 0.8, display = "all", all = TRUE, endpoint = NULL, ...)

Arguments

Value

A ggplot object showing estimated power and its Monte Carlo confidence interval.

Description

Plot fixed-sample-size power results

Usage

## S3 method for class 'simpower_curve'
plot(x, target_power = 0.8, display = "all", all = TRUE, endpoint = NULL, ...)

Arguments

Value

A ggplot object showing estimated power and its Monte Carlo confidence interval as a clearly visible vertical line.

Description

Generates a detailed plot showing the relationship between power and total sample size for each comparator and the overall combined comparators. The combined-comparator panel is omitted when only one comparator is present. The plot also includes confidence intervals for power estimates and highlights the target power with a dashed line for easy visual comparison.

Usage

## S3 method for class 'simss'
plot(x, target_power = 0.8, display = "all", all = TRUE, endpoint = NULL, ...)

Arguments

Details

The plot dynamically adjusts to exclude unnecessary components, such as redundant endpoints or comparators with insufficient data, ensuring clarity and simplicity. The ggplot2 framework is used for visualizations, allowing further customization if needed.

Value

A ggplot object illustrating:

• Power (y-axis) vs. Total Sample Size (x-axis) for individual endpoints and comparators.

• Clearly visible vertical lines representing the 95% confidence interval of the power estimates.

• A dashed horizontal line indicating the target power for comparison.

• A larger outlined point at the selected sample size.

• Faceted panels for each comparator, making it easy to compare results across different groups.

Author(s)

Johanna Muñoz johanna.munoz@fromdatatowisdom.com

Description

The plot displays the complete-trial Type I error at all evaluated boundaries. The worst-case scenario is highlighted with a thicker interval and a larger point, and its estimated value is shown next to the point. Error bars are 95% Monte Carlo confidence intervals.

Usage

## S3 method for class 'type1error'
plot(x, ...)

Arguments

Value

A ggplot object.

Description

Displays the complete-trial Type I error for the minimal required boundary scenarios by default. The worst-case displayed scenario is highlighted with a thicker interval and a larger point, and its estimated value is shown directly above the point. The full scenario table, including larger null counts, remains available in the returned object and can be displayed with null_count = "all". The dashed line is the nominal alpha level. The dotted line is the simultaneous one-sided Monte Carlo upper bound for the maximum.

Usage

## S3 method for class 'type1error_joint'
plot(x, null_count = c("minimal", "all"), ...)

Arguments

Value

A ggplot object.

Description

Computes the statistical power for testing the difference of means (DOM) between two groups using Monte Carlo simulations. The power is estimated based on specified sample sizes, means, standard deviations, and significance level.

Usage

power_dom(
  seed,
  mu_test,
  mu_control,
  sigma_test,
  sigma_control,
  N_test,
  N_control,
  lb,
  ub,
  alpha = 0.05,
  nsim = 10000
)

Arguments

Value

Numeric. Estimated power (probability between 0 and 1).

Description

Print count-outcome power results

Usage

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

Arguments

Description

Print count-outcome sample-size results

Usage

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

Arguments

Description

Print fixed-sample-size power results

Usage

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

Arguments

Value

The input object, invisibly.

Description

Prints the summary results of the sample size estimation for bioequivalence trials, including achieved power, total sample size, and power confidence intervals. The function also details the study design, primary endpoint comparisons, and applied multiplicity corrections.

Usage

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

Arguments

Details

This function displays key metrics from a sample size estimation analysis. It provides an overview of the study design, treatment comparisons, tested endpoints, significance level adjustments, and estimated sample size. For studies with multiple primary endpoints, it describes the multiplicity correction applied.

Value

No return value, called for side effects. The function prints the summary results of the sample size estimation to the console in a structured format.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

Description

Print a Mielke sample-size result

Usage

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

Arguments

Description

Dispatches to the compiled simulation routine for a selected trial design and test type.

Usage

run_simulations(design = c("parallel", "2x2"), ctype = c("DOM", "ROM"), ...)

Arguments

Value

The result returned by the selected simulation routine.

Description

This function simulates a 2x2 crossover trial across multiple iterations. It evaluates equivalence across multiple endpoints using the Difference of Means (DOM) test.

Usage

run_simulations_2x2_dom(
  nsim,
  n,
  muT,
  muR,
  SigmaW,
  lequi_tol,
  uequi_tol,
  alpha,
  sigmaB,
  dropout,
  Eper,
  Eco,
  typey,
  adseq,
  k,
  arm_seed
)

Arguments

Details

This function evaluates equivalence using the Difference of Means (DOM) test. Equivalence is determined based on predefined lower (lequi_tol) and upper (uequi_tol) equivalence thresholds, and hypothesis testing is conducted at the specified significance level (alpha). If adseq is TRUE, primary endpoints must establish equivalence before secondary endpoints are evaluated. The sample size per period is adjusted based on dropout rates, ensuring valid study conclusions. The simulation incorporates within-subject correlation using SigmaW and accounts for between-subject variance with sigmaB. Expected period effects (Eper) and carryover effects (Eco) are included in the model. A fixed random seed (arm_seed) is used to ensure reproducibility across simulations.

Value

A numeric matrix where each column stores simulation results: The first row (totaly) represents the overall equivalence decision (1 = success, 0 = failure). Subsequent rows contain equivalence decisions per endpoint, mean estimates for the treatment group, mean estimates for the reference group, standard deviations for treatment, and standard deviations for reference.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

Description

This function simulates a 2x2 crossover trial across multiple iterations. It evaluates equivalence across multiple endpoints using the Ratio of Means (ROM) test.

Usage

run_simulations_2x2_rom(
  nsim,
  n,
  muT,
  muR,
  SigmaW,
  lequi_tol,
  uequi_tol,
  alpha,
  sigmaB,
  dropout,
  Eper,
  Eco,
  typey,
  adseq,
  k,
  arm_seed
)

Arguments

Details

This function evaluates equivalence using the Ratio of Means (ROM) test. Equivalence is determined based on predefined lower lequi_tol and upper uequi_tol equivalence thresholds, and hypothesis testing is conducted at the specified significance level alpha. If adseq is TRUE, primary endpoints must establish equivalence before secondary endpoints are evaluated. The sample size per period is adjusted based on dropout rates, ensuring valid study conclusions. The simulation incorporates within-subject correlation using SigmaW and accounts for between-subject variance with sigmaB. Expected period effects Eper and carryover effects Eco are included in the model. A fixed random seed arm_seed is used to ensure reproducibility across simulations.//'

Value

A numeric matrix where each column stores simulation results: The first row (totaly) represents the overall equivalence decision (1 = success, 0 = failure). Subsequent rows contain equivalence decisions per endpoint, mean estimates for the treatment group, mean estimates for the reference group, standard deviations for treatment, and standard deviations for reference.

@author Thomas Debray tdebray@fromdatatowisdom.com

Description

This function simulates a parallel-group trial across multiple iterations. It evaluates equivalence across multiple endpoints using the Difference of Means (DOM) test.

Usage

run_simulations_par_dom(
  nsim,
  n,
  muT,
  muR,
  SigmaT,
  SigmaR,
  lequi_tol,
  uequi_tol,
  alpha,
  dropout,
  typey,
  adseq,
  k,
  arm_seed_T,
  arm_seed_R,
  TART,
  TARR,
  vareq
)

Arguments

Details

Equivalence testing uses either the Difference of Means (DOM) test, applying predefined equivalence thresholds and significance levels. When hierarchical testing (adseq) is enabled, all primary endpoints must demonstrate equivalence before secondary endpoints are evaluated. Dropout rates are incorporated into the sample size calculation to ensure proper adjustment. Randomization is controlled through separate random seeds for the treatment and reference groups, enhancing reproducibility.

Value

The function returns an arma::mat storing simulation results row-wise for consistency with R's output format. The first row (totaly) contains the overall equivalence decision (1 for success, 0 for failure). The subsequent rows include equivalence deicisons for each endpoint, mean estimates for both treatment and reference groups, and corresponding standard deviations.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

Description

This function simulates a parallel-group trial across multiple iterations. It evaluates equivalence across multiple endpoints using the Ratio of Means (ROM) test.

Usage

run_simulations_par_rom(
  nsim,
  n,
  muT,
  muR,
  SigmaT,
  SigmaR,
  lequi_tol,
  uequi_tol,
  alpha,
  dropout,
  typey,
  adseq,
  k,
  arm_seed_T,
  arm_seed_R,
  TART,
  TARR,
  vareq
)

Arguments

Details

Equivalence testing uses either the Ratio of Means (ROM) test, applying predefined equivalence thresholds and significance levels. When hierarchical testing (adseq) is enabled, all primary endpoints must demonstrate equivalence before secondary endpoints are evaluated. Dropout rates are incorporated into the sample size calculation to ensure proper adjustment. Randomization is controlled through separate random seeds for the treatment and reference groups, enhancing reproducibility.

Value

The function returns an arma::mat storing simulation results row-wise for consistency with R's output format. The first row (totaly) contains the overall equivalence decision (1 for success, 0 for failure). The subsequent rows include equivalence decisions for each endpoint, mean estimates for both treatment and reference groups, and corresponding standard deviations.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

Description

Computes the required sample size to achieve a target power in studies with multiple endpoints and treatment arms. The function employs modified root-finding algorithms to estimate sample size while accounting for correlation structures, variance assumptions, and equivalence bounds across endpoints. It is particularly useful for bioequivalence trials and multi-arm studies with complex endpoint structures.

Usage

sampleSize(
  distribution = c("norm", "lnorm", "pois", "nbinom"),
  mu_list = NULL,
  varcov_list = NA,
  sigma_list = NA,
  cor_mat = NA,
  sigmaB = NA,
  rate_list = NULL,
  exposure = 1,
  dispersion = 0.1,
  Eper = c(0, 0),
  Eco = c(0, 0),
  rho = 0,
  TAR = rep(1, length(mu_list)),
  arm_names = NA,
  ynames_list = NA,
  type_y = NA,
  list_comparator = NA,
  list_y_comparator = NA,
  power = 0.8,
  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,
  optimization_method = "fast",
  lower = 2,
  upper = 500,
  step.power = 6,
  step.up = TRUE,
  pos.side = FALSE,
  maxiter = 1000,
  verbose = FALSE,
  keep_sim_data = FALSE,
  .warn_redundant_bon = TRUE
)

Arguments

Details

The common planning arguments are power, alpha, list_comparator, list_lequi.tol, list_uequi.tol, k, adjust, dtype, dropout, nsim, seed, lower, and upper. Use the following distribution-specific arguments in addition to those common arguments:

Normal and Log Normal

Supply mu_list, sigma_list or varcov_list; use cor_mat or rho for endpoint dependence. The ctype argument selects DOM or ROM testing.

Poisson and Negative Binomial

Supply rate_list, list_comparator, and comparator-specific list_lequi.tol and list_uequi.tol. Use exposure and, for negative-binomial outcomes, dispersion; both may be scalar, endpoint-specific, or named arm-specific lists. Continuous-outcome arguments are ignored.

For count outcomes, optimization_method = "fast" brackets the first sample size whose simulated power reaches the target and refines the bracket by integer bisection. The "step-by-step" option remains available when a complete candidate-by-candidate power table is preferred. The fast method assumes the usual approximately monotone power curve and uses the same seed at each candidate to reduce simulation noise. The effective endpoint count is comparator-specific: when list_y_comparator is omitted, only endpoints present in both arms are tested; when it is supplied, only the listed endpoints are tested. k is validated against that comparator-specific count and oversized values are capped with a warning. Formal endpoint-wise adjustment is unnecessary when all selected endpoints are required (k = m), although requested Bonferroni or Sidak adjustment remains available with a warning. For k < m, adjust = "no" is explicitly reported as an uncalibrated choice. For a k-of-m decision, adjust = "t" applies Mielke's strong \(k\)-out-of-\(m\) calibration alpha / (m - k + 1). The legacy adjust = "pc" label is accepted as an alias. For continuous and count outcomes, type_y is used with adjust = "seq"; named endpoint vectors are aligned to the selected comparator endpoints. Count analyses use the same primary-gate and secondary-family decision rule as the continuous kernels. The unified function returns primary class simss for all outcome distributions. Count results retain countss as a secondary compatibility class. Use summary() and plot() to inspect the result.

Value

A list containing:

response

Array summarizing simulation results, including estimated sample sizes, achieved power, and confidence intervals.

table.iter

Data frame showing estimated sample sizes and calculated power at each iteration. For count outcomes, one row is retained for every evaluated candidate.

table.test

Data frame containing test results for all simulated trials. For count outcomes, this 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.

param.u

Original input parameters.

param

Final adjusted parameters used in sample size calculation.

param.d

Trial design parameters used in the simulation.

sim_data

Optional long-format simulated observations, returned when keep_sim_data = TRUE.

References

Schuirmann, D. J. (1987). A comparison of the Two One-Sided Tests procedure and the Power approach for assessing the equivalence of average bioavailability. Journal of Pharmacokinetics and Biopharmaceutics, 15(6), 657-680. https://doi.org/10.1007/BF01068419

Mielke, J., Jones, B., Jilma, B., & König, F. (2018). Sample size for multiple hypothesis testing in biosimilar development. Statistics in Biopharmaceutical Research, 10(1), 39-49. https://doi.org/10.1080/19466315.2017.1371071

Berger, R. L., & Hsu, J. C. (1996). Bioequivalence trials, intersection-union tests, and equivalence confidence sets. Statistical Science, 283-302.

Sozu, T., Sugimoto, T., Hamasaki, T., & Evans, S. R. (2015). "Sample Size Determination in Clinical Trials with Multiple Endpoints." SpringerBriefs in Statistics. https://doi.org/10.1007/978-3-319-22005-5

Examples

mu_list <- list(SB2 = c(AUCinf = 38703, AUClast = 36862, Cmax = 127.0),
                EUREF = c(AUCinf = 39360, AUClast = 37022, Cmax = 126.2),
                USREF = c(AUCinf = 39270, AUClast = 37368, Cmax = 129.2))

sigma_list <- list(SB2 = c(AUCinf = 11114, AUClast = 9133, Cmax = 16.9),
                   EUREF = c(AUCinf = 12332, AUClast = 9398, Cmax = 17.9),
                   USREF = c(AUCinf = 10064, AUClast = 8332, Cmax = 18.8))

# Equivalent boundaries
lequi.tol <- c(AUCinf = 0.8, AUClast = 0.8, Cmax = 0.8)
uequi.tol <- c(AUCinf = 1.25, AUClast = 1.25, Cmax = 1.25)

# Arms to be compared
list_comparator <- list(EMA = c("SB2", "EUREF"),
                        FDA = c("SB2", "USREF"))

# Endpoints to be compared
list_y_comparator <- list(EMA = c("AUCinf", "Cmax"),
                          FDA = c("AUClast", "Cmax"))

# Equivalence boundaries for each comparison
lequi_lower <- c(AUCinf = 0.80, AUClast = 0.80, Cmax = 0.80)
lequi_upper <- c(AUCinf = 1.25, AUClast = 1.25, Cmax = 1.25)

# Run the simulation
sampleSize(power = 0.9, alpha = 0.05, mu_list = mu_list,
           sigma_list = sigma_list, list_comparator = list_comparator,
           list_y_comparator = list_y_comparator,
           list_lequi.tol = list("EMA" = lequi_lower, "FDA" = lequi_lower),
           list_uequi.tol = list("EMA" = lequi_upper, "FDA" = lequi_upper),
           adjust = "no", dtype = "parallel", ctype = "ROM", vareq = FALSE,
           distribution = "lnorm", ncores = 1, nsim = 50, seed = 1234)

# The same entry point for a two-arm Poisson count-rate calculation:
sampleSize(power = 0.80, distribution = "Poisson",
           rate_list = list(TEST = 0.21, REF = 0.20),
           list_comparator = list(TEST_vs_REF = c("TEST", "REF")),
           list_lequi.tol = list(TEST_vs_REF = 0.80),
           list_uequi.tol = list(TEST_vs_REF = 1.25),
           exposure = 10, lower = 20, upper = 500,
           nsim = 100, seed = 1234)

Description

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

Usage

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

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)

Description

Estimate sample size for joint correlated count equivalence

Usage

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

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.

Description

Estimates the required sample size to achieve a specified power level for multiple hypothesis testing, using the approach described by Mielke et al. (2018). This function is particularly useful for bioequivalence or biosimilar studies with multiple correlated endpoints, where a minimum number of endpoints must meet equivalence criteria.

Usage

sampleSize_Mielke(
  power,
  Nmax,
  m,
  k,
  rho,
  sigma,
  true.diff,
  equi.tol,
  design,
  alpha,
  adjust = "no",
  seed = NULL,
  nsim = 10000
)

Arguments

Details

This function uses the method proposed by Mielke et al. (2018) to estimate the sample size required to achieve the desired power level in studies with multiple correlated endpoints. The function iteratively increases sample size until the target power is reached or the maximum allowable sample size (Nmax) is exceeded. The approach accounts for endpoint correlation and supports adjustments for multiple testing using various correction methods.

Value

An object of class simss_mielke, containing:

"power.a"

Achieved power with the estimated sample size.

"SS"

Required sample size per sequence to achieve the target power.

References

Mielke, J., Jones, B., Jilma, B. & König, F. Sample Size for Multiple Hypothesis Testing in Biosimilar Development. Statistics in Biopharmaceutical Research 10, 39–49 (2018).

Examples

# Example 1 from Mielke
sampleSize_Mielke(power = 0.8, Nmax = 1000, m = 5, k = 5, rho = 0,
                  sigma = 0.3, true.diff =  log(1.05), equi.tol = log(1.25),
                  design = "parallel", alpha = 0.05, adjust = "no",
                  seed = 1234, nsim = 100)

Description

Generate simulated endpoint data for a parallel design, with options for normal and lognormal distributions.

Usage

simParallelEndpoints(
  n,
  mu.arithmetic,
  mu.geometric = NULL,
  Sigma,
  CV = NULL,
  seed,
  dist = "normal"
)

Arguments

Value

A matrix of simulated endpoint values for a parallel design, with dimensions n by the number of variables in mu.arithmetic or mu.geometric.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

Description

Calculates simulated power for a prespecified sample size. The outcome family is selected through distribution, matching the unified sampleSize() interface.

Usage

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
)

Arguments

Details

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.

Value

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.

Examples

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)

Description

SimTOST: A Package for Sample Size Simulations

Details

The SimTOST package provides tools for simulating sample sizes, calculating power, and assessing type-I error for various statistical scenarios.

Planning

Each function name links to its full help page.

• sampleSize: simulation-based sample-size planning for continuous and count outcomes, including multiple endpoints and comparator families.

• simPower: simulated power for a fixed sample size, with support for continuous and count-outcome analyses.

• sampleSize_Mielke: Mielke et al.'s sample-size calculation for multiple, correlated hypotheses and k-out-of-m rules.

Continuous outcomes

• simParallelEndpoints: generates correlated normal or log-normal endpoint data for a parallel-group design.

• get_par: prepares and validates endpoint, covariance, allocation, and hierarchy parameters for planning.

• run_simulations: dispatches a continuous simulation to the selected design and test combination.

Simulation-result methods

• print.simss (print): prints a concise design, power, confidence-interval, and sample-size report.

• summary.simss (summary): returns and prints a structured summary of the simulation result.

• confint.simss (confint): extracts the stored Monte Carlo confidence interval for achieved power.

• plot.simss (plot): plots simulated power against sample size with confidence intervals and the target-power line.

• update.simss and update.simpower (update): reruns a result while replacing only explicitly supplied planning or simulation parameters.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com (author and maintainer)

Other contributors:

• Tim Friede tim.friede@med.uni-goettingen.de [contributor]

• Johanna Munoz johanna.munoz@fromdatatowisdom.com [contributor]

• Dewi Amaliah dewi.amaliah@fromdatatowisdom.com [contributor]

• Wei Wei wei.wei@biogen.com [contributor]

• Marian Mitroiu marian.mitroiu@biogen.com [contributor]

• Scott McDonald scott.mcdonald@fromdatatowisdom.com [contributor]

• Biogen Inc [copyright holder, funder] (original implementation v1.0.0)

• Smart Data Analysis and Statistics B.V. [copyright holder, funder] (subsequent developments)

References

Mielke, J., Jones, B., Jilma, B. & König, F. Sample Size for Multiple Hypothesis Testing in Biosimilar Development. Statistics in Biopharmaceutical Research 10, 39–49 (2018).

See Also

Useful links:

• https://smartdata-analysis-and-statistics.github.io/SimTOST/

Description

Summarize count-outcome power results

Usage

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

Arguments

Value

A data frame containing the design, model, sample size, estimated power, and Monte Carlo confidence interval.

Description

Prints the same design-oriented sample-size report used for continuous outcomes. Count-specific result fields and search histories are retained in the object, while the invisible return value is a data frame of the selected per-arm (or per-sequence) and total sample sizes.

Usage

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

Arguments

Value

Invisibly, a data frame containing the selected sample size for each arm (or sequence) and the total sample size.

Description

Summarize fixed-sample-size power results

Usage

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

Arguments

Value

A data frame containing the distribution, design, comparison, estimand, hypotheses, sample size, estimated power, and Monte Carlo confidence interval.

Description

Generates a summary of the simulation results, including per-arm and total sample sizes. The printed summary also states the equivalence null and alternative hypotheses for the selected outcome and design.

Usage

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

Arguments

Value

Invisibly, a data frame containing the estimated sample size for each arm (or sequence), plus the total sample size. The printed report also includes the design, estimand, equivalence margins, target power, achieved power, and Monte Carlo interval. Count-outcome results use this same report and retain their count-specific fields in the returned object.

Author(s)

Johanna Muñoz johanna.munoz@fromdatatowisdom.com

Examples

## Not run: 
res <- sampleSize(mu_list = list(T = c(y1 = 1), R = c(y1 = 1)),
                  sigma_list = list(T = c(y1 = .2), R = c(y1 = .2)),
                  list_comparator = list(c("T", "R")),
                  list_lequi.tol = list(c(y1 = .8)),
                  list_uequi.tol = list(c(y1 = 1.25)),
                  ctype = "ROM", distribution = "lnorm", nsim = 10,
                  lower = 2, upper = 4)
summary(res)

## End(Not run)

Description

Simulates a two-sequence, two-period (2x2) crossover design and evaluate equivalence for the difference of means (DOM).

Usage

test_2x2_dom(
  n,
  muT,
  muR,
  SigmaW,
  lequi_tol,
  uequi_tol,
  alpha,
  sigmaB,
  dropout,
  Eper,
  Eco,
  typey,
  adseq,
  k,
  arm_seed
)

Arguments

Value

A numeric matrix containing the simulated hypothesis test results. The first column represents the overall equivalence decision, where 1 indicates success and 0 indicates failure. The subsequent columns contain the hypothesis test results for each endpoint, followed by mean estimates for the reference and treatment groups, and standard deviations for the reference and treatment groups.

Description

Simulates a two-sequence, two-period (2x2) crossover design and evaluate equivalence for the ratio of means (ROM).

Usage

test_2x2_rom(
  n,
  muT,
  muR,
  SigmaW,
  lequi_tol,
  uequi_tol,
  alpha,
  sigmaB,
  dropout,
  Eper,
  Eco,
  typey,
  adseq,
  k,
  arm_seed
)

Arguments

Value

A numeric matrix containing the simulated hypothesis test results. The first column represents the overall equivalence decision, where 1 indicates success and 0 indicates failure. The subsequent columns contain the hypothesis test results for each endpoint, followed by mean estimates for the reference and treatment groups, and standard deviations for the reference and treatment groups.

Description

Simulates a parallel-group design and performs equivalence testing using the difference of means (DOM) approach. This function evaluates whether the treatment and reference groups are equivalent based on predefined equivalence margins and hypothesis testing criteria.

Usage

test_par_dom(
  n,
  muT,
  muR,
  SigmaT,
  SigmaR,
  lequi_tol,
  uequi_tol,
  alpha,
  dropout,
  typey,
  adseq,
  k,
  arm_seedT,
  arm_seedR,
  TART,
  TARR,
  vareq
)

Arguments

Details

The function simulates a parallel-group study design and evaluates equivalence using the difference of means (DOM) approach. It accounts for dropout rates and treatment allocation proportions while generating simulated data based on the specified covariance structure. The test statistics are computed, and a final equivalence decision is made based on the predefined number of required significant endpoints (k). If sequential testing (adseq) is enabled, primary endpoints must establish equivalence before secondary endpoints are evaluated. When vareq = TRUE, the test assumes equal variances between groups and applies Schuirmann's two one-sided tests (TOST).

Value

A numeric matrix containing the simulated hypothesis test results. The first column represents the overall equivalence decision, where 1 indicates success and 0 indicates failure. The subsequent columns contain the hypothesis test results for each endpoint, followed by mean estimates for the reference and treatment groups, and standard deviations for the reference and treatment groups.

Description

Simulates a parallel-group design and performs equivalence testing using the ratio of means (ROM) approach. This function evaluates whether the treatment and reference groups are equivalent based on predefined equivalence margins and hypothesis testing criteria.

Usage

test_par_rom(
  n,
  muT,
  muR,
  SigmaT,
  SigmaR,
  lequi_tol,
  uequi_tol,
  alpha,
  dropout,
  typey,
  adseq,
  k,
  arm_seedT,
  arm_seedR,
  TART,
  TARR,
  vareq
)

Arguments

Details

The function simulates a parallel-group study design and evaluates equivalence using the ratio of means (ROM) approach. It accounts for dropout rates and treatment allocation proportions while generating simulated data based on the specified covariance structure. The test statistics are computed, and a final equivalence decision is made based on the predefined number of required significant endpoints (k). If sequential testing (adseq) is enabled, primary endpoints must establish equivalence before secondary endpoints are evaluated. When vareq = TRUE, the test assumes equal variances between groups and applies Schuirmann's two one-sided tests (TOST).

Value

A numeric matrix containing the simulated hypothesis test results. The first column represents the overall equivalence decision, where 1 indicates success and 0 indicates failure. The subsequent columns contain the hypothesis test results for each endpoint, followed by mean estimates for the reference and treatment groups, and standard deviations for the reference and treatment groups.

Description

Generates a boundary-null configuration and estimates its empirical rejection probability using simPower(). The comparator convention is c(test, reference). For normal ROM and count RR, a lower-bound null sets mean(test) / mean(reference) = L. For log-normal ROM, the boundary is imposed on the log-analysis scale used by the test; this coincides with the arithmetic mean ratio when the two arms have the same coefficient of variation.

Usage

type1Error(
  null = c("lower", "upper", "both"),
  x = NULL,
  comparator = NULL,
  endpoint = NULL,
  joint = FALSE,
  conf.level = 0.95,
  ...
)

Arguments

Details

Comparators use the convention c(test, reference). For ROM, the tested estimand is test / reference; for DOM it is test - reference. With log-normal ROM, the test is performed after converting the supplied original-scale means and variances to the log-analysis scale, so the boundary scenario is calibrated on that scale. For count rate ratios, the analogous midpoint is sqrt(L * U) on the rate-ratio scale because the test is performed on the log-rate-ratio scale. Absolute rates and dispersion remain nuisance parameters, so this midpoint should be supplemented by a grid or optimization when a global supremum is required. If a comparator has m endpoints and requires k endpoints to pass, a composite null configuration has at least m - k + 1 non-equivalent endpoints. With joint = TRUE, all endpoint subsets with boundary counts from m - k + 1 through m, and all lower/upper direction combinations, are evaluated, while the complete decision still requires the k-of-m rule for every comparator in the same simulated trial. The returned joint object includes a Bonferroni simultaneous one-sided Monte Carlo upper bound for the maximum scenario probability.

Value

For null = "lower" or "upper", an object of class type1error containing the empirical Type I error in type1_error and its Monte Carlo interval. For null = "both", a named list containing the lower- and upper-bound results. With joint = TRUE, a type1error_joint object containing one joint result for every valid comparator, endpoint-subset, boundary-direction combination is returned.

Description

Update a standalone count power calculation

Usage

## S3 method for class 'countpower'
update(object, ..., evaluate = TRUE)

Arguments

Value

A newly calculated count power object, or an unevaluated call.

Description

Update a standalone count sample-size calculation

Usage

## S3 method for class 'countss'
update(object, ..., evaluate = TRUE)

Arguments

Value

A newly calculated count sample-size object, or an unevaluated call.

Description

Update a SimTOST fixed-sample-size power calculation

Usage

## S3 method for class 'simpower'
update(object, ..., evaluate = TRUE)

Arguments

Value

A newly calculated simpower object, or an unevaluated call.

Description

Re-runs the calculation represented by object, replacing only arguments supplied in .... This is useful for changing, for example, the target power or number of simulations without repeating the complete original call.

Usage

## S3 method for class 'simss'
update(object, ..., evaluate = TRUE)

Arguments

Value

A newly calculated object of the same result family as object, or an unevaluated call when evaluate = FALSE.