Update hierarchical test & vignettes

Author: NightlordTW

R/RcppExports.R

@@ -293,16 +293,106 @@ run_simulations_par <- function(nsim, n, muT, muR, SigmaT, SigmaR, lequi_tol, ue
     .Call(`_SimTOST_run_simulations_par`, nsim, n, muT, muR, SigmaT, SigmaR, lequi_tol, uequi_tol, alpha, dropout, typey, adseq, k, arm_seed_T, arm_seed_R, ctype, lognorm, TART, TARR, vareq)
 }
 
-#' @title Run Simulations for a 2x2 Crossover Design
+#' @title Run Simulations for a Parallel Design with Difference of Means (DOM) test
 #'
 #' @description
-#' This function simulates a 2x2 crossover study design across multiple iterations (`nsim`).
-#' It evaluates equivalence testing for multiple endpoints using either the
-#' Difference of Means (DOM) or Ratio of Means (ROM) approach.
+#' This function simulates a parallel-group trial across multiple iterations.
+#' It evaluates equivalence across multiple endpoints using the
+#' Difference of Means (DOM) test.
+#'
+#' @param nsim Integer. The number of simulations to run.
+#' @param n Integer. The sample size per arm (before dropout).
+#' @param muT arma::vec. Mean vector for the treatment arm.
+#' @param muR arma::vec. Mean vector for the reference arm.
+#' @param SigmaT arma::mat. Covariance matrix for the treatment arm.
+#' @param SigmaR arma::mat. Covariance matrix for the reference arm.
+#' @param lequi_tol arma::rowvec. Lower equivalence thresholds for each endpoint.
+#' @param uequi_tol arma::rowvec. Upper equivalence thresholds for each endpoint.
+#' @param alpha arma::rowvec. Significance level (α) for each endpoint.
+#' @param dropout arma::vec. Dropout rates for each arm (T, R).
+#' @param typey Integer vector indicating the classification of each endpoint, where `1` corresponds to a primary endpoint and `2` corresponds to a secondary endpoint.
+#' @param adseq Boolean. If `TRUE`, applies sequential (hierarchical) testing.
+#' @param k Integer. Minimum number of endpoints required for equivalence.
+#' @param arm_seed_T arma::ivec. Random seed vector for the treatment group (one per simulation).
+#' @param arm_seed_R arma::ivec. Random seed vector for the reference group (one per simulation).
+#' @param TART Double. Treatment allocation ratio (proportion of subjects in treatment arm).
+#' @param TARR Double. Reference allocation ratio (proportion of subjects in reference arm).
+#' @param vareq Boolean. If `TRUE`, assumes equal variances across treatment and reference groups.
+#'
+#' @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.
+#'
+#' @return
+#' 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 Thomas Debray \email{[email protected]}
+#' @export
+run_simulations_par_dom <- function(nsim, n, muT, muR, SigmaT, SigmaR, lequi_tol, uequi_tol, alpha, dropout, typey, adseq, k, arm_seed_T, arm_seed_R, TART, TARR, vareq) {
+    .Call(`_SimTOST_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)
+}
+
+#' @title 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.
+#'
+#' @param nsim Integer. The number of simulations to run.
+#' @param n Integer. The sample size per arm (before dropout).
+#' @param muT arma::vec. Mean vector for the treatment arm.
+#' @param muR arma::vec. Mean vector for the reference arm.
+#' @param SigmaT arma::mat. Covariance matrix for the treatment arm.
+#' @param SigmaR arma::mat. Covariance matrix for the reference arm.
+#' @param lequi_tol arma::rowvec. Lower equivalence thresholds for each endpoint.
+#' @param uequi_tol arma::rowvec. Upper equivalence thresholds for each endpoint.
+#' @param alpha arma::rowvec. Significance level (α) for each endpoint.
+#' @param dropout arma::vec. Dropout rates for each arm (T, R).
+#' @param typey Integer vector indicating the classification of each endpoint, where `1` corresponds to a primary endpoint and `2` corresponds to a secondary endpoint.
+#' @param adseq Boolean. If `TRUE`, applies sequential (hierarchical) testing.
+#' @param k Integer. Minimum number of endpoints required for equivalence.
+#' @param arm_seed_T arma::ivec. Random seed vector for the treatment group (one per simulation).
+#' @param arm_seed_R arma::ivec. Random seed vector for the reference group (one per simulation).
+#' @param TART Double. Treatment allocation ratio (proportion of subjects in treatment arm).
+#' @param TARR Double. Reference allocation ratio (proportion of subjects in reference arm).
+#' @param vareq Boolean. If `TRUE`, assumes equal variances across treatment and reference groups.
+#'
+#' @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.
+#'
+#' @return
+#' 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 Thomas Debray \email{[email protected]}
+#' @export
+run_simulations_par_rom <- function(nsim, n, muT, muR, SigmaT, SigmaR, lequi_tol, uequi_tol, alpha, dropout, typey, adseq, k, arm_seed_T, arm_seed_R, TART, TARR, vareq) {
+    .Call(`_SimTOST_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)
+}
+
+#' @title 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.
 #'
 #' @param nsim Integer. The number of simulations to run.
-#' @param ctype Character string. Testing method (`"DOM"` for Difference of Means, `"ROM"` for Ratio of Means).
-#' @param lognorm Boolean. If `TRUE`, assumes log-normal distribution for endpoints.
 #' @param n Integer. The sample size per period.
 #' @param muT Numeric vector. Mean outcomes for the active treatment.
 #' @param muR Numeric vector. Mean outcomes for the reference treatment.
@@ -320,7 +410,7 @@ run_simulations_par <- function(nsim, n, muT, muR, SigmaT, SigmaR, lequi_tol, ue
 #' @param arm_seed Integer vector. Random seed for each simulation.
 #'
 #' @details
-#' This function performs equivalence testing using either the Difference of Means (DOM) or Ratio of Means (ROM) approach.
+#' This function evaluates equivalence using either 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.
@@ -332,13 +422,60 @@ run_simulations_par <- function(nsim, n, muT, muR, SigmaT, SigmaR, lequi_tol, ue
 #' @return
 #' 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 p-values for equivalence testing per endpoint (`E1, E2, ...`),
+#' Subsequent rows contain equivalence decisions per endpoint (`E1, E2, ...`),
 #' mean estimates for the treatment group (`mu_E1_T, mu_E2_T, ...`), mean estimates for the reference group (`mu_E1_R, mu_E2_R, ...`),
 #' standard deviations for treatment (`sd_E1_T, sd_E2_T, ...`), and standard deviations for reference (`sd_E1_R, sd_E2_R, ...`).
 #'
 #' @author Thomas Debray \email{[email protected]}
 #' @export
-run_simulations_2x2 <- function(nsim, ctype, lognorm, n, muT, muR, SigmaW, lequi_tol, uequi_tol, alpha, sigmaB, dropout, Eper, Eco, typey, adseq, k, arm_seed) {
-    .Call(`_SimTOST_run_simulations_2x2`, nsim, ctype, lognorm, n, muT, muR, SigmaW, lequi_tol, uequi_tol, alpha, sigmaB, dropout, Eper, Eco, typey, adseq, k, arm_seed)
+run_simulations_2x2_dom <- function(nsim, n, muT, muR, SigmaW, lequi_tol, uequi_tol, alpha, sigmaB, dropout, Eper, Eco, typey, adseq, k, arm_seed) {
+    .Call(`_SimTOST_run_simulations_2x2_dom`, nsim, n, muT, muR, SigmaW, lequi_tol, uequi_tol, alpha, sigmaB, dropout, Eper, Eco, typey, adseq, k, arm_seed)
+}
+
+#' @title 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.
+#'
+#' @param nsim Integer. The number of simulations to run.
+#' @param n Integer. The sample size per period.
+#' @param muT Numeric vector. Mean outcomes for the active treatment.
+#' @param muR Numeric vector. Mean outcomes for the reference treatment.
+#' @param SigmaW Numeric matrix. Within-subject covariance matrix for endpoints.
+#' @param lequi_tol Numeric vector. Lower equivalence thresholds for each endpoint.
+#' @param uequi_tol Numeric vector. Upper equivalence thresholds for each endpoint.
+#' @param alpha Numeric vector. Significance levels for hypothesis testing across endpoints.
+#' @param sigmaB Numeric. Between-subject variance for the crossover model.
+#' @param dropout Numeric vector of size 2. Dropout rates for each sequence.
+#' @param Eper Numeric vector. Expected period effects for each sequence.
+#' @param Eco Numeric vector. Expected carryover effects for each sequence.
+#' @param typey Integer vector indicating the classification of each endpoint, where `1` corresponds to a primary endpoint and `2` corresponds to a secondary endpoint.
+#' @param adseq Logical. If `TRUE`, applies sequential (hierarchical) testing.
+#' @param k Integer. Minimum number of endpoints required for equivalence.
+#' @param arm_seed Integer vector. Random seed for each simulation.
+#'
+#'  @details
+#'  This function evaluates equivalence using either 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.
+#'
+#'  @return
+#'  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 (`E1, E2, ...`),
+#'  mean estimates for the treatment group (`mu_E1_T, mu_E2_T, ...`), mean estimates for the reference group (`mu_E1_R, mu_E2_R, ...`),
+#'  standard deviations for treatment (`sd_E1_T, sd_E2_T, ...`), and standard deviations for reference (`sd_E1_R, sd_E2_R, ...`).
+#'
+#'  @author Thomas Debray \email{[email protected]}
+#' @export
+run_simulations_2x2_rom <- function(nsim, n, muT, muR, SigmaW, lequi_tol, uequi_tol, alpha, sigmaB, dropout, Eper, Eco, typey, adseq, k, arm_seed) {
+    .Call(`_SimTOST_run_simulations_2x2_rom`, nsim, n, muT, muR, SigmaW, lequi_tol, uequi_tol, alpha, sigmaB, dropout, Eper, Eco, typey, adseq, k, arm_seed)
 }
 

R/SampleSize.R

@@ -229,20 +229,24 @@ sampleSize <- function(mu_list, varcov_list = NA, sigma_list = NA, cor_mat = NA,
 
   # Define weights according to type of endpoint,i.e. primary, secondary
 
-  if (any(is.na(type_y)) | length(type_y) != length(uynames)) {
-    type_y <- rep(1,length(uynames))
-  }
-
-  names(type_y) <- uynames
+  if (adjust != "seq" | any(is.na(type_y)) | length(type_y) != length(uynames)) {
+    type_y <- -1
+    weight_seq <- rep(1, length(uynames))
+  } else {
+    names(type_y) <- uynames
 
+    # Count number of secondary endpoints (elements equal to 2 in type_y)
+    num_secondary_endpoints <- sum(type_y == 2)
 
-  weight <- 1/table(type_y)
-  weight_seq <- type_y
+    # Initialize weight vector with 1s
+    weight_seq <- rep(1, length(type_y))
 
-  for (x in unique(type_y)) {
-    weight_seq[weight_seq == x] <- weight[x]
+    # Assign 1 / num_secondary_endpoints to secondary endpoints
+    if (num_secondary_endpoints > 0) {
+      weight_seq[type_y == 2] <- 1 / num_secondary_endpoints
+    }
+    names(weight_seq) <- uynames
   }
-  names(weight_seq) <- uynames
 
   #if (len_mu[[1]] == 1){
   #  mu_list <- lapply(mu_list,FUN = function(x){array(unlist(x))})