Moved construction of varcov_list to dedicated function

Author: NightlordTW

R/SampleSize.R

@@ -165,50 +165,14 @@ sampleSize <- function(mu_list, varcov_list = NA, sigma_list = NA, cor_mat = NA,
     mu_list[[i]] <- mu
   }
 
+  # Derive the list of covariance matrices
+  varcov_list <- derive_varcov_list(mu_list = mu_list, sigma_list = sigma_list,
+                                    ynames_list = ynames_list,
+                                    varcov_list = varcov_list, cor_mat = cor_mat,
+                                    rho = rho)
 
 
 
-  # Varcov specfication
-  if (any(is.na(varcov_list))) {
-    if (any(is.na(sigma_list))) {
-      stop("No variance-covariance matrix provided, and a standard deviation list is also missing. Either a variance-covariance matrix or a standard deviation list is required.")
-    }
-
-    # length in terms of endpoints
-    len_mu <- sapply(mu_list,length)
-    len_sd <- sapply(sigma_list,length)
-    len_y <- sapply(ynames_list,length) # number of endpoints
-
-    if (any((len_mu != len_sd) | (len_mu != len_y))) {
-      stop("In each arm, 'mu', 'sigma', and 'y_name' must have the same length.")
-    }
-
-    varcov_list <- NULL
-
-    for (i in 1:n) {
-      m <- length(sigma_list[[i]]) # number of endpoints
-
-      if (m == 1) {
-        varcov <- as.matrix(sigma_list[[i]]^2)
-
-      } else {
-        R <- matrix(rho, m, m)
-        diag(R) <- 1 # correlation matrix
-
-        if (any(!is.na(cor_mat))) {
-          if ((nrow(cor_mat) == m) & (ncol(cor_mat) == m)) {
-            R <- as.matrix(cor_mat)
-          } else {
-            warning("An uncorrelated matrix will be used as the provided matrix does not have the expected dimensions.")
-          }
-        }
-
-        varcov <- diag(sigma_list[[i]]) %*% R %*% diag(sigma_list[[i]])
-      }
-
-      varcov_list[[i]] <-  varcov
-    }
-  }
 
   weight_seq <- NA
   param.u <- list(mu = mu_list, varcov = varcov_list, TAR_list = TAR_list,
@@ -697,4 +661,78 @@ derive_allocation_rate <- function(TAR = NULL, arm_names, verbose = FALSE) {
   return(TAR_list)
 }
 
+#' Derive Variance-Covariance Matrix List
+#'
+#' Constructs a list of variance-covariance matrices for multiple treatment arms based on provided standard deviations,
+#' means, and correlation structures.
+#'
+#' @param mu_list A list of numeric vectors representing the means (\eqn{\mu}) for each treatment arm. Each element corresponds to one arm.
+#' @param sigma_list A list of numeric vectors representing the standard deviations (\eqn{\sigma}) for each treatment arm. Each element corresponds to one arm.
+#' @param ynames_list A list of character vectors specifying the names of the endpoints for each arm. Each element corresponds to one arm.
+#' @param varcov_list (Optional) A pre-specified list of variance-covariance matrices for each arm. If provided, it will override the construction of variance-covariance matrices.
+#' @param cor_mat (Optional) A correlation matrix to be used for constructing the variance-covariance matrices when there are multiple endpoints. If dimensions do not match the number of endpoints, a warning is issued.
+#' @param rho (Optional) A numeric value specifying the constant correlation coefficient to be used between all pairs of endpoints if no correlation matrix is provided. Default is 0 (uncorrelated endpoints).
+#'
+#' @details
+#' This function creates a list of variance-covariance matrices for multiple treatment arms. If the \code{varcov_list} is not provided,
+#' the function uses the \code{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 \code{cor_mat} or the constant correlation coefficient \code{rho}.
+#'
+#' The function ensures that the lengths of \code{mu_list}, \code{sigma_list}, and \code{ynames_list} match for each arm. If dimensions mismatch,
+#' or if neither a variance-covariance matrix (\code{varcov_list}) nor a standard deviation list (\code{sigma_list}) is provided, an error is raised.
+#'
+#' @return A list of variance-covariance matrices, one for each treatment arm.
+#'
+#' @author Thomas Debray \email{[email protected]}
+derive_varcov_list <- function(mu_list, sigma_list, ynames_list, varcov_list = NULL, cor_mat = NULL, rho = 0) {
+  # Check if variance-covariance matrix is missing
+  if (any(is.na(varcov_list))) {
+    if (any(is.na(sigma_list))) {
+      stop("No variance-covariance matrix provided, and a standard deviation list is also missing. Either a variance-covariance matrix or a standard deviation list is required.")
+    }
+
+    # Validate lengths of inputs
+    len_mu <- sapply(mu_list, length)
+    len_sd <- sapply(sigma_list, length)
+    len_y <- sapply(ynames_list, length) # Number of endpoints
+
+    if (any((len_mu != len_sd) | (len_mu != len_y))) {
+      stop("In each arm, 'mu', 'sigma', and 'y_name' must have the same length.")
+    }
+
+    # Initialize the varcov_list
+    varcov_list <- vector("list", length(mu_list))
+
+    # Loop through each arm to construct the variance-covariance matrices
+    for (i in seq_along(sigma_list)) {
+      m <- length(sigma_list[[i]]) # Number of endpoints
+
+      if (m == 1) {
+        # Single endpoint: variance is the square of the standard deviation
+        varcov <- as.matrix(sigma_list[[i]]^2)
+      } else {
+        # Multiple endpoints: construct the correlation matrix
+        R <- matrix(rho, m, m)
+        diag(R) <- 1 # Set diagonal to 1 (self-correlation)
+
+        # Use the provided correlation matrix if dimensions match
+        if (any(!is.na(cor_mat))) {
+          if ((nrow(cor_mat) == m) & (ncol(cor_mat) == m)) {
+            R <- as.matrix(cor_mat)
+          } else {
+            warning("An uncorrelated matrix will be used as the provided matrix does not have the expected dimensions.")
+          }
+        }
+
+        # Construct the variance-covariance matrix
+        varcov <- diag(sigma_list[[i]]) %*% R %*% diag(sigma_list[[i]])
+      }
+
+      # Add the matrix to the list
+      varcov_list[[i]] <- varcov
+    }
+  }
+
+  return(varcov_list)
+}
 

man/derive_varcov_list.Rd

@@ -91,10 +91,10 @@ library(SimTOST)
 ))
 ```
 
-When testing each PK measure independently, the total sample size is `r sim_AUCinf$response$n_total` for AUCinf, `r sim_AUClast$response$n_total` for AUClast, and `r sim_Cmax$response$n_total` for Cmax. This means that we would have to enroll `r sim_AUCinf$response$n_total` + `r sim_AUClast$response$n_total` + `r sim_Cmax$response$n_total` = `r sim_AUCinf$response$n_total + sim_AUClast$response$n_total + sim_Cmax$response$n_total` patients in order to reject $H_0$ at a significance level of 5\%. For context, the original trial was a randomized, single-blind, three-arm, parallel-group study conducted in 159 healthy subjects, slightly more than the `r sim_AUCinf$response$n_total + sim_AUClast$response$n_total + sim_Cmax$response$n_total` patients estimated to be necessary. This suggests that the original trial had a small buffer above the calculated sample size requirements.
+When testing each PK measure independently, the total sample size is `r sim_AUCinf$response$n_total` for AUCinf, `r sim_AUClast$response$n_total` for AUClast, and `r sim_Cmax$response$n_total` for Cmax. This means that we would have to enroll `r sim_AUCinf$response$n_total` + `r sim_AUClast$response$n_total` + `r sim_Cmax$response$n_total` = `r sim_AUCinf$response$n_total + sim_AUClast$response$n_total + sim_Cmax$response$n_total` patients in order to reject $H_0$. Note that the significance level of this combined test is then $0.05^3$. For context, the original trial was a randomized, single-blind, three-arm, parallel-group study conducted in 159 healthy subjects, slightly more than the `r sim_AUCinf$response$n_total + sim_AUClast$response$n_total + sim_Cmax$response$n_total` patients estimated to be necessary.
 
 # Simultaneous Testing of Independent Co-Primary Endpoints
-This approach focuses on simultaneous testing of PK measures while assuming independence between endpoints. Unlike the previous approach, which tested each PK measure independently, this method integrates comparisons across multiple endpoints, accounting for correlations (or lack thereof) between them, thus enabling simultaneous testing for equivalence without inflating the overall Type I error rate.
+This approach focuses on simultaneous testing of PK measures while assuming independence between endpoints. Unlike the previous approach, which tested each PK measure independently, this approach integrates comparisons across multiple endpoints while directly controlling the overall Type I error rate at a pre-specified level.
 
 ## Key Assumptions
 In the calculations below, the following assumptions are made:
@@ -213,7 +213,7 @@ Imagine that we are interested in demonstrating equivalence for at least $k=1$ o
   seed = 1234                # Random seed for reproducibility
 ))
 ```
-As mentioned in [the Introduction](../articles/intopkg.html), Bonferroni adjustment is often overly conservative, especially in scenarios with correlated tests. A less restrictive alternative is the *k*-adjustment, which specifically accounts for the number of tests and the number of endpoints required for equivalence.
+As mentioned in [the Introduction](../articles/intropkg.html), Bonferroni adjustment is often overly conservative, especially in scenarios with correlated tests. A less restrictive alternative is the *k*-adjustment, which specifically accounts for the number of tests and the number of endpoints required for equivalence.
 
 ```{r}
 (N_mp_k <- sampleSize(