Revise examples hierarchical testing

Author: NightlordTW

R/RcppExports.R

@@ -35,30 +35,24 @@ ptvdf <- function(x, df, lower) {
     .Call(`_SimTOST_ptvdf`, x, df, lower)
 }
 
-#' @title Check Equivalence
+#' @title Check Equivalence for Multiple Endpoints
 #'
 #' @description
-#' This function evaluates whether equivalence criteria are met.
-#' 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 structured matrix that includes equivalence decisions,
-#' test results, mean estimates, and standard deviations.
+#' 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 matrix indicating whether equivalence is established.
 #'
 #' @param typey An unsigned integer vector (`arma::uvec`) indicating the type of each endpoint:
 #'              - `1` = Primary endpoint
 #'              - `2` = Secondary endpoint
 #' @param adseq A boolean flag (`TRUE` if sequential testing is enabled).
 #'              - If `TRUE`, all primary endpoints must pass equivalence for secondary endpoints to be evaluated.
 #'              - If `FALSE`, primary and secondary endpoints are evaluated independently.
-#' @param tbioq A matrix (`arma::mat`) indicating the equivalence test results:
+#' @param tbioq A matrix (`arma::mat`) containing the equivalence test results for each endpoint:
 #'              - `1` = Equivalence met
 #'              - `0` = Equivalence not met
 #' @param k An integer specifying the minimum number of endpoints required to establish equivalence.
-#' @param mu0 A matrix (`arma::mat`) containing the estimated means for the reference treatment group.
-#' @param mu1 A matrix (`arma::mat`) containing the estimated means for the treatment under evaluation.
-#' @param sd0 A matrix (`arma::mat`) containing the standard deviations for the reference treatment group.
-#' @param sd1 A matrix (`arma::mat`) containing the standard deviations for the treatment under evaluation.
 #'
 #' @details
 #' - **Sequential Adjustment (`adseq = TRUE`)**:
@@ -70,14 +64,13 @@ ptvdf <- function(x, df, lower) {
 #'   - `0` otherwise.
 #'
 #' @return
-#' An `arma::mat` containing the final equivalence decision along with test statistics:
-#' - `totaly` (1 × 1 matrix): Binary indicator (1 = equivalence established, 0 = not established).
-#' - `tbioq` (m × n matrix): Equivalence test results for each endpoint.
-#' - `mu0, mu1` (m × n matrices): Mean estimates for the reference and treatment groups.
-#' - `sd0, sd1` (m × n matrices): Standard deviations for the reference and treatment groups.
-#' @expor
-check_equivalence <- function(typey, adseq, tbioq, k, mu0, mu1, sd0, sd1) {
-    .Call(`_SimTOST_check_equivalence`, typey, adseq, tbioq, k, mu0, mu1, sd0, sd1)
+#' An `arma::mat` (1 × 1 matrix) containing a binary equivalence decision:
+#' - `1` = Equivalence established.
+#' - `0` = Equivalence not established.
+#'
+#' @export
+check_equivalence <- function(typey, adseq, tbioq, k) {
+    .Call(`_SimTOST_check_equivalence`, typey, adseq, tbioq, k)
 }
 
 #' @title Simulate a 2x2 Crossover Design and Compute Difference of Means (DOM)

R/SampleSize.R

@@ -235,6 +235,7 @@ sampleSize <- function(mu_list, varcov_list = NA, sigma_list = NA, cor_mat = NA,
 
   names(type_y) <- uynames
 
+
   weight <- 1/table(type_y)
   weight_seq <- type_y
 

R/utils.R

@@ -193,7 +193,7 @@ test_studies <- function(nsim, n, comp, param, param.d, arm_seed, ncores){
   if (adjust=="bon") {alpha <- rep(alphau/(m),m)}
   if (adjust=="sid") {alpha <- rep(1-(1-alphau)^{1/m},m)}
   if (adjust=="k") { alpha <- rep(k*alphau/(m),m)}
-  if (adjust=="seq"){
+  if (adjust == "seq"){
     alpha <- alphau*param$weight_seq[endp]
     }
 

man/check_equivalence.Rd

@@ -38,20 +38,16 @@ BEGIN_RCPP
 END_RCPP
 }
 // check_equivalence
-arma::mat check_equivalence(const arma::uvec& typey, bool adseq, const arma::mat& tbioq, int k, const arma::mat& mu0, const arma::mat& mu1, const arma::mat& sd0, const arma::mat& sd1);
-RcppExport SEXP _SimTOST_check_equivalence(SEXP typeySEXP, SEXP adseqSEXP, SEXP tbioqSEXP, SEXP kSEXP, SEXP mu0SEXP, SEXP mu1SEXP, SEXP sd0SEXP, SEXP sd1SEXP) {
+arma::mat check_equivalence(const arma::uvec& typey, bool adseq, const arma::mat& tbioq, int k);
+RcppExport SEXP _SimTOST_check_equivalence(SEXP typeySEXP, SEXP adseqSEXP, SEXP tbioqSEXP, SEXP kSEXP) {
 BEGIN_RCPP
     Rcpp::RObject rcpp_result_gen;
     Rcpp::RNGScope rcpp_rngScope_gen;
     Rcpp::traits::input_parameter< const arma::uvec& >::type typey(typeySEXP);
     Rcpp::traits::input_parameter< bool >::type adseq(adseqSEXP);
     Rcpp::traits::input_parameter< const arma::mat& >::type tbioq(tbioqSEXP);
     Rcpp::traits::input_parameter< int >::type k(kSEXP);
-    Rcpp::traits::input_parameter< const arma::mat& >::type mu0(mu0SEXP);
-    Rcpp::traits::input_parameter< const arma::mat& >::type mu1(mu1SEXP);
-    Rcpp::traits::input_parameter< const arma::mat& >::type sd0(sd0SEXP);
-    Rcpp::traits::input_parameter< const arma::mat& >::type sd1(sd1SEXP);
-    rcpp_result_gen = Rcpp::wrap(check_equivalence(typey, adseq, tbioq, k, mu0, mu1, sd0, sd1));
+    rcpp_result_gen = Rcpp::wrap(check_equivalence(typey, adseq, tbioq, k));
     return rcpp_result_gen;
 END_RCPP
 }
@@ -165,7 +161,7 @@ RcppExport SEXP _rcpp_module_boot_test();
 static const R_CallMethodDef CallEntries[] = {
     {"_SimTOST_ptv", (DL_FUNC) &_SimTOST_ptv, 3},
     {"_SimTOST_ptvdf", (DL_FUNC) &_SimTOST_ptvdf, 3},
-    {"_SimTOST_check_equivalence", (DL_FUNC) &_SimTOST_check_equivalence, 8},
+    {"_SimTOST_check_equivalence", (DL_FUNC) &_SimTOST_check_equivalence, 4},
     {"_SimTOST_test_2x2_dom", (DL_FUNC) &_SimTOST_test_2x2_dom, 15},
     {"_SimTOST_test_2x2_rom", (DL_FUNC) &_SimTOST_test_2x2_rom, 15},
     {"_SimTOST_test_par_dom", (DL_FUNC) &_SimTOST_test_par_dom, 17},

src/RcppExports.cpp

@@ -60,30 +60,24 @@ arma::mat ptvdf(arma::mat x, arma::mat df, bool lower) {
   return arma::reshape(y, 1, n);
 }
 
-//' @title Check Equivalence
+//' @title Check Equivalence for Multiple Endpoints
 //'
 //' @description
-//' This function evaluates whether equivalence criteria are met.
-//' 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 structured matrix that includes equivalence decisions,
-//' test results, mean estimates, and standard deviations.
+//' 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 matrix indicating whether equivalence is established.
 //'
 //' @param typey An unsigned integer vector (`arma::uvec`) indicating the type of each endpoint:
 //'              - `1` = Primary endpoint
 //'              - `2` = Secondary endpoint
 //' @param adseq A boolean flag (`TRUE` if sequential testing is enabled).
 //'              - If `TRUE`, all primary endpoints must pass equivalence for secondary endpoints to be evaluated.
 //'              - If `FALSE`, primary and secondary endpoints are evaluated independently.
-//' @param tbioq A matrix (`arma::mat`) indicating the equivalence test results:
+//' @param tbioq A matrix (`arma::mat`) containing the equivalence test results for each endpoint:
 //'              - `1` = Equivalence met
 //'              - `0` = Equivalence not met
 //' @param k An integer specifying the minimum number of endpoints required to establish equivalence.
-//' @param mu0 A matrix (`arma::mat`) containing the estimated means for the reference treatment group.
-//' @param mu1 A matrix (`arma::mat`) containing the estimated means for the treatment under evaluation.
-//' @param sd0 A matrix (`arma::mat`) containing the standard deviations for the reference treatment group.
-//' @param sd1 A matrix (`arma::mat`) containing the standard deviations for the treatment under evaluation.
 //'
 //' @details
 //' - **Sequential Adjustment (`adseq = TRUE`)**:
@@ -95,36 +89,25 @@ arma::mat ptvdf(arma::mat x, arma::mat df, bool lower) {
 //'   - `0` otherwise.
 //'
 //' @return
-//' An `arma::mat` containing the final equivalence decision along with test statistics:
-//' - `totaly` (1 × 1 matrix): Binary indicator (1 = equivalence established, 0 = not established).
-//' - `tbioq` (m × n matrix): Equivalence test results for each endpoint.
-//' - `mu0, mu1` (m × n matrices): Mean estimates for the reference and treatment groups.
-//' - `sd0, sd1` (m × n matrices): Standard deviations for the reference and treatment groups.
+//' An `arma::mat` (1 × 1 matrix) containing a binary equivalence decision:
+//' - `1` = Equivalence established.
+//' - `0` = Equivalence not established.
+//'
 //' @export
 // [[Rcpp::export]]
 arma::mat check_equivalence(const arma::uvec& typey, bool adseq,
-                            const arma::mat& tbioq, int k,
-                            const arma::mat& mu0, const arma::mat& mu1,
-                            const arma::mat& sd0, const arma::mat& sd1) {
+                            const arma::mat& tbioq, int k) {
   // primary endpoints in case of sequencial adjustment
-  int sumtypey;
+  int sumtypey = 1;
   // in case no primary endpoint is added.
-  if( accu(typey) >= 0) {
+  if (!typey.empty() && all(typey >= 0)) {
     sumtypey = accu(tbioq.cols(typey)); // sum of primary endpoint rejected
-  }else{
-    sumtypey = 1;
   }
 
   // Total number of primary endpoints
   int lentypey = typey.n_elem;
 
-  // Determine if all primary endpoints meet the equivalence criteria under sequential adjustment.
-  //
-  // If `adseq` (sequential testing) is disabled (`false`), equivalence is not required for all primary endpoints,
-  // so `sumpe` is automatically set to `true`.
-  //
-  // If `adseq` is enabled (`true`), `sumpe` is set to `true` only if all primary endpoints (`sumtypey`) meet
-  // the required equivalence criteria (`lentypey`), meaning all must pass.
+  // Determine if all primary endpoints meet the equivalence criteria under sequential adjustment
   bool sumpe = !adseq || (sumtypey == lentypey);
 
   // Check if at least `k` endpoints meet equivalence criteria
@@ -134,13 +117,7 @@ arma::mat check_equivalence(const arma::uvec& typey, bool adseq,
   arma::mat totaly(1,1);
   totaly(0, 0) = (sumt && sumpe) ? 1 : 0;
 
-  // Combine results into a response matrix
-  arma::mat response0 = join_rows(totaly, tbioq);
-  arma::mat response1 = join_rows(mu0, mu1);
-  arma::mat response2 = join_rows(sd0, sd1);
-  arma::mat response3 = join_rows(response0, response1);
-
-  return join_rows(response3, response2);
+  return totaly;
 }
 
 
@@ -569,8 +546,16 @@ arma::mat test_par_dom(int n, arma::vec muT, arma::vec muR,
    mat alpha0 = conv_to<mat>::from(alpha);
    mat tbioq  = conv_to<mat>::from((ptost < alpha0));
 
-   // Call the check_equivalence function
-   return check_equivalence(typey, adseq, tbioq, k, mu0, mu1, sd0, sd1);
+   // Call the check_equivalence function to determine if equivalence is established
+   arma::mat totaly = check_equivalence(typey, adseq, tbioq, k);
+
+   // Combine results into a response matrix
+   arma::mat response0 = join_rows(totaly, tbioq);
+   arma::mat response1 = join_rows(mu0, mu1);
+   arma::mat response2 = join_rows(sd0, sd1);
+   arma::mat response3 = join_rows(response0, response1);
+
+   return join_rows(response3, response2);
 }
 
 //' @title Simulate a Parallel Design and Compute Ratio of Means (ROM)
@@ -673,8 +658,16 @@ arma::mat test_par_rom(int n, arma::vec muT, arma::vec muR,
    mat alpha0 = conv_to<mat>::from(alpha);
    mat tbioq  = conv_to<mat>::from((ptost < alpha0));
 
-   // Call the check_equivalence function
-   return check_equivalence(typey, adseq, tbioq, k, mu0, mu1, sd0, sd1);
+   // Call the check_equivalence function to determine if equivalence is established
+   arma::mat totaly = check_equivalence(typey, adseq, tbioq, k);
+
+   // Combine results into a response matrix
+   arma::mat response0 = join_rows(totaly, tbioq);
+   arma::mat response1 = join_rows(mu0, mu1);
+   arma::mat response2 = join_rows(sd0, sd1);
+   arma::mat response3 = join_rows(response0, response1);
+
+   return join_rows(response3, response2);
 }
 
 

src/module.cpp

@@ -150,20 +150,19 @@ $$\alpha_k= \frac{k*\alpha}{m}$$
 where $k$ is the number of endpoints required for equivalence, and $m$ is the total number of endpoints evaluated.
 
 ## Hierarchical testing of multiple endpoints
-Hierarchical testing is an approach to multiple endpoint testing where endpoints are tested in a predefined order, typically based on their clinical or regulatory importance. A fallback testing strategy is applied, allowing sequential hypothesis testing. If a hypothesis earlier in the sequence fails to be rejected, testing stops, and subsequent hypotheses are not evaluated.
+Hierarchical testing is an approach to multiple endpoint testing where endpoints are tested in a predefined order, typically based on their clinical or regulatory importance. A fallback testing strategy is applied, allowing sequential hypothesis testing. If a hypothesis earlier in the sequence fails to be rejected, testing stops, and subsequent hypotheses are not evaluated. [@chowdhry_finding_2024]
 
-To implement hierarchical testing in SimTOST, the user defines primary and secondary endpoints using the `type_y` vector argument. The significance level ($\alpha$) is adjusted separately for each endpoint group:
+To implement hierarchical testing in SimTOST, the user specifies `adjust = "seq"` in the [sampleSize()](../reference/sampleSize.html) function and defines primary and secondary endpoints using the `type_y` vector argument. The significance level ($\alpha$) is adjusted separately for each group of endpoints, ensuring strong control of the Family-Wise Error Rate (FWER) while maintaining interpretability.
 
 1. **Evaluate primary endpoints**  
    - Testing begins with the pre-specified primary endpoints.
-   - The adjusted significance level for a primary endpoint $p$ is: $$\alpha_H= \frac{\alpha}{\text{Number of primary endpoints}}$$
-   - If any primary hypothesis fails to be rejected, testing stops, and secondary endpoints are not tested.
+   - The adjusted significance level for a primary endpoint $p$ is: $$\alpha_p= \frac{\alpha}{\text{Number of primary endpoints}}$$
+   - If any primary endpoint fails to meet the equivalence criteria, testing stops, and secondary endpoints are not tested.
 2. **Proceed to secondary endpoints (if applicable)**  
-   - If all primary endpoints demonstrate equivalence, testing continues to the secondary endpoints.
-   - A Bonferroni adjustment is applied again, based on the number of secondary endpoints.
-
-The adjusted significance level is determined using a weighting approach, ensuring that primary and secondary endpoints are tested sequentially while maintaining strong control over the Family-Wise Error Rate (FWER). The sequential adjustment correction can be implemented by specifying `adjust = "seq"` in the [sampleSize()](../reference/sampleSize.html) function.
-
+   - If all primary endpoints meet the equivalence criteria, testing proceeds to the secondary endpoints.
+   - The significance level for a secondary endpoint $s$ is adjusted as: $$\alpha_s= \frac{\alpha}{\text{Number of secondary endpoints}}$$
+3. **Final Decision**
+   - The test is considered successful if at least `k` endpoints meet equivalence and all primary endpoints pass.
 
 An example of hierarchical testing can be found in [this vignette](sampleSize_parallel_2A3E.html#hierarchical-testing).
 

vignettes/intropkg.Rmd

@@ -179,3 +179,18 @@ @incollection{PASSch685
   publisher    = {NCSS Statistical Software},
   url          = {https://www.ncss.com/wp-content/themes/ncss/pdf/Procedures/PASS/Biosimilarity_Tests_for_the_Difference_Between_Means_using_a_Parallel_Two-Group_Design.pdf}
 }
+
+@article{chowdhry_finding_2024,
+  title = {Finding {{Multiple Signals}} in the {{Noise}}: {{Handling Multiplicity}} in {{Clinical Trials}}},
+  shorttitle = {Finding {{Multiple Signals}} in the {{Noise}}},
+  author = {Chowdhry, Amit K. and Park, John and Kang, John and Sakthivel, Gukan and Pugh, Stephanie},
+  year = {2024},
+  month = jul,
+  journal = {International Journal of Radiation Oncology*Biology*Physics},
+  volume = {119},
+  number = {3},
+  pages = {750--755},
+  issn = {03603016},
+  doi = {10.1016/j.ijrobp.2023.12.007}
+}
+