Package {SimTOST}

Sample Size Estimation via Simulation

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/

Calculate the power across all comparators

Description

Internal function to calculate the power across all comparators

Usage

.normalize_internal_distribution(param.d)

Arguments

Value

power calculated from a global list of comparators

Plot simulated endpoint correlations

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.

Estimate joint power for correlated count endpoints and multiple comparisons

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)

Estimate power for count-rate equivalence

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)

Select the smallest plotted sample size that reaches the target power.

Description

The sample-size search may evaluate candidates in a non-monotone order. Plot selection must therefore be based on the plotted global total-power rows, not on the order in which the optimizer evaluated candidates.

Usage

.select_power_plot_n(data, target_power, n_col, fallback = NA_real_)

Preserve named-vector indexing for legacy Mielke examples

Description

Preserve named-vector indexing for legacy Mielke examples

Usage

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

Arguments

Coerce a Mielke result to a numeric sample size

Description

Coerce a Mielke result to a numeric sample size

Usage

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

Arguments

Check Equivalence for Multiple Endpoints

Description

This function evaluates whether equivalence criteria are met based on a predefined set of endpoints. It first checks whether all primary endpoints satisfy equivalence (if sequential testing is enabled). Then, it determines whether the required number of endpoints (k) meet the equivalence threshold. The function returns a binary decision indicating whether overall equivalence is established.

Usage

check_equivalence(typey, adseq, tbioq, k)

Arguments

Details

When sequential testing is enabled (adseq = TRUE), all primary endpoints must meet equivalence before secondary endpoints are considered. If sequential testing is disabled (adseq = FALSE), all endpoints are evaluated simultaneously without hierarchical constraints. The function then determines whether at least k endpoints meet the equivalence criteria. If the conditions are satisfied, the final equivalence decision (totaly) is 1; otherwise, it is 0.

Value

Returns a (1 × 1 matrix) containing a binary equivalence decision. A value of 1 indicates that equivalence is established, while 0 indicates that equivalence is not established.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

Extract the Monte Carlo confidence interval from count power results

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.

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

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.

Confidence Interval for Achieved Power from simss object

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)

Derive and Validate Treatment Allocation Rate (TAR)

Description

This function validates and adjusts the treatment allocation rate (TAR) to ensure it is correctly specified for the given number of treatment arms (n_arms). If TAR is missing or NULL, it is assigned a default vector of ones, ensuring equal allocation across all arms. The function also handles cases where TAR is shorter than n_arms, contains NA values, or has invalid values.

Usage

derive_allocation_rate(TAR = NULL, arm_names, verbose = FALSE)

Arguments

Value

A named list representing the treatment allocation rate for each arm.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

Derive or Assign Arm Names

Description

This function checks if arm_names is provided. If arm_names is missing, it attempts to derive names from mu_list. If mu_list does not contain names, it assigns default names ("A1", "A2", etc.) to each arm. Informational messages are displayed if verbose is set to TRUE.

Usage

derive_arm_names(arm_names, mu_list, verbose = FALSE)

Arguments

Value

A vector of arm names.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

Derive Endpoint Names

Description

Derive Endpoint Names

Usage

derive_endpoint_names(ynames_list, mu_list, verbose = FALSE)

Arguments

Value

A list of endpoint names for each arm.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

This function derives endpoint names (ynames_list) from mu_list if ynames_list is missing. If ynames_list is already provided, it confirms the names to the user when verbose is set to TRUE.

Derive Variance-Covariance Matrix List

Description

Constructs a list of variance-covariance matrices for multiple treatment arms based on provided standard deviations, means, and correlation structures.

Usage

derive_varcov_list(
  mu_list,
  sigma_list,
  ynames_list = NULL,
  varcov_list = NULL,
  cor_mat = NULL,
  rho = 0
)

Arguments

Details

This function creates a list of variance-covariance matrices for multiple treatment arms. If the varcov_list is not provided, the function uses the sigma_list to compute the matrices. For single endpoints, the variance is simply the square of the standard deviation. For multiple endpoints, the function constructs the matrices using either a provided cor_mat or the constant correlation coefficient rho.

The function ensures that the lengths of mu_list, sigma_list, and ynames_list match for each arm. If dimensions mismatch, or if neither a variance-covariance matrix (varcov_list) nor a standard deviation list (sigma_list) is provided, an error is raised.

Value

A list of variance-covariance matrices, one for each treatment arm.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

Parameter Configuration for Endpoints and Comparators

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"))

Helper function for conditional messages

Description

This function displays a message if the verbose parameter is set to TRUE. It is useful for providing optional feedback to users during function execution.

Usage

info_msg(message, verbose)

Arguments

Value

NULL (invisible). This function is used for side effects (displaying messages).

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

Plot count-outcome power results

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.

Plot count-outcome sample-size results

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.

Plot fixed-sample-size power results

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.

Plot fixed-sample-size power results

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.

Plot Power vs Sample Size for Simulation Results

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

Plot empirical Type I error

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.

Plot joint Type I error scenarios

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.

Plot simulated decision heatmaps

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.

Plot distributions of retained simulated observations

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.

Plot Monte Carlo error

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.

Plot simulation stability

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.

Power Calculation for Hypothesis Testing in Equivalence Trials

Description

Estimates the power of hypothesis testing in equivalence trials using the method described by Mielke et al. This approach accounts for multiple endpoints, correlation structures, and multiplicity adjustments.

Usage

power_Mielke(
  N,
  m,
  k,
  R,
  sigma,
  true.diff,
  equi.tol = log(1.25),
  design,
  alpha = 0.05,
  adjust = "no",
  nsim = 10000
)

Arguments

Value

A numeric value representing the estimated power based on the simulations.

Power Calculation for Difference of Means (DOM) Hypothesis Test

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).

Prepare inputs for a joint multi-arm count simulation

Description

Prepare inputs for a joint multi-arm count simulation

Usage

prepare_joint_count_inputs(
  rates,
  comparisons,
  exposure,
  margin_lower,
  margin_upper,
  alpha,
  endpoint_corr,
  list_margin_lower = NULL,
  list_margin_upper = NULL,
  dispersion = 0.1
)

Print count-outcome power results

Description

Print count-outcome power results

Usage

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

Arguments

Print count-outcome sample-size results

Description

Print count-outcome sample-size results

Usage

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

Arguments

Print fixed-sample-size power results

Description

Print fixed-sample-size power results

Usage

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

Arguments

Value

The input object, invisibly.

Print Summary of Sample Size Estimation

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

Print a Mielke sample-size result

Description

Print a Mielke sample-size result

Usage

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

Arguments

Compute p-values for a t-distribution with Fixed Degrees of Freedom

Description

Computes p-values for a given set of random variables under a t-distribution with fixed degrees of freedom.

Usage

ptv(x, df, lower)

Arguments

Value

A numeric matrix containing the computed cumulative distribution function (CDF) values (p-values).

Calculate p-values using t-distribution with Variable Degrees of Freedom

Description

This function computes the cumulative distribution function (p-values) for a given random variable x and corresponding degrees of freedom df using the t-distribution. The function can compute the lower or upper tail probabilities depending on the value of the lower argument.

Usage

ptvdf(x, df, lower)

Arguments

Value

arma::mat (vector) - A matrix containing the computed cumulative distribution function (p-values) for each element in x. The result is returned as a 1xN matrix, where N is the number of elements in x.

Run a design-specific simulation

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.

Run Simulations for a 2x2 Crossover Design with Difference of Means (DOM) test

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

Run Simulations for a 2x2 Crossover Design with Ratio of Means (ROM) test

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

Run Simulations for a Parallel Design with Difference of Means (DOM) test

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

Run Simulations for a Parallel Design with Ratio of Means (ROM) test

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

Sample Size Calculation for Bioequivalence and Multi-Endpoint Studies

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)

Sample Size Estimation for Multiple Hypothesis Testing Using Mielke's Method

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)

Estimate sample size for count-rate equivalence

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)

Estimate sample size for joint correlated count equivalence

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.

Simulated Test Statistic for Noninferiority/Equivalence Trials

Description

Simulates test statistics for multiple hypothesis testing in biosimilar development, following the approach described by Mielke et al. (2018). It calculates the necessary sample size for meeting equivalence criteria across multiple endpoints while considering correlation structures and applying multiplicity adjustments.

Usage

sign_Mielke(
  N,
  m,
  k,
  R,
  sigma,
  true.diff,
  equi.tol = log(1.25),
  design,
  alpha = 0.05,
  adjust = "no"
)

Arguments

Details

This function is designed for multiple-endpoint clinical trials, where success is defined as meeting equivalence criteria for at least a subset of tests. Simulated test statistics are based on multivariate normal distribution assumptions, and the function supports k-out-of-m success criteria for regulatory approval.

The adjustment options follow the multiple-endpoint framework of Mielke et al. (2018). In particular, adjust = "k" uses the weak k-adjustment k * alpha / m, whereas adjust = "t" uses the strong k-out-of-m adjustment alpha / (m - k + 1) for partial null configurations. This distinction is particularly relevant for biosimilar studies, where sample size estimation must account for multiple comparisons across endpoints, doses, or populations.

Value

An object of class simss_mielke. It contains the legacy fields SS and power.a, together with n_per_sequence, n_total, power, and the target and input parameters. Use summary() for a data-frame summary, print() for a concise report, or as.numeric() to extract SS.

References

Kong, L., Kohberger, R. C., & Koch, G. G. (2004). Type I Error and Power in Noninferiority/Equivalence Trials with Correlated Multiple Endpoints: An Example from Vaccine Development Trials. Journal of Biopharmaceutical Statistics, 14(4), 893–907.

Lehmann, E. L., & Romano, J. P. (2005). Generalizations of the Familywise Error Rate. The Annals of Statistics, 33(2), 1138–1154.

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.

Generate Simulated Endpoint Data for Parallel Group Design

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

Estimate power at a fixed sample size

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)

Summarize count-outcome power results

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.

Summary for Count Sample-Size Results

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.

Summarize fixed-sample-size power results

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.

Summary for Simulation Results

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)

Simulate a 2x2 Crossover Design and Compute Difference of Means (DOM)

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.

Simulate a 2x2 Crossover Design and Compute Ratio of Means (ROM)

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.

Simulate a Parallel Design and Test Difference of Means (DOM)

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.

Simulate a Parallel Design and Test Ratio of Means (ROM)

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.

test_studies

Description

Internal function to estimate the bioequivalence test for nsim simulated studies given a sample size n

Usage

test_studies(nsim, n, comp, param, param.d, arm_seed, ncores)

Arguments

Value

a logical matrix of size (nsim) X (number of endpoints + 1) function only replicates test_bioq nsim times.

Empirical Type I Error at the Least-Favorable Null

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.

Optimizer for Uniroot Integer (Modified)

Description

A modified integer-based root-finding algorithm for determining the sample size required to achieve a target power. This function extends the uniroot integer search method to handle cases with stepwise power searches while considering constraints on search limits.

Usage

uniroot.integer.mod(
  f,
  power,
  lower = lower,
  upper = upper,
  step.power = step.power,
  step.up = step.up,
  pos.side = pos.side,
  maxiter = maxiter,
  ...
)

Arguments

Value

A list containing:

root

The integer value closest to the root on the correct side.

f.root

Value of f at the estimated root.

iter

Number of function evaluations performed.

table.iter

A data frame showing estimated sample size (N) and corresponding power at each iteration.

table.test

A data frame containing endpoint-level test results for each simulation and corresponding N.

Update a standalone count power calculation

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.

Update a standalone count sample-size calculation

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.

Update a SimTOST fixed-sample-size power calculation

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.

Update a SimTOST sample-size calculation

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.

Validate Positive Semi-Definite Matrices

Description

Validates that all matrices in a list are symmetric and positive semi-definite.

Usage

validate_positive_definite(varcov_list)

Arguments

Value

NULL. If all matrices pass, the function returns nothing. If any matrix fails, it stops with an error message.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com

Check Sample Size Limits

Description

Validates that the upper and lower limits are numeric and that the upper limit is greater than the lower limit.

Usage

validate_sample_size_limits(lower, upper)

Arguments

Value

NULL. If the checks pass, the function returns nothing. If the checks fail, it stops execution with an error message.

Author(s)

Thomas Debray tdebray@fromdatatowisdom.com