rename parameters

Author: Liyang Fei

R/BarcodePairCorrelation.R

@@ -28,7 +28,7 @@
 #' @export
 #'
 #' @import ggplot2
-#' @importFrom magrittr  %>%
+#' @importFrom magrittr %>%
 #' @import data.table
 #'
 #' @examples

R/createBarbieQ.R

@@ -5,33 +5,32 @@
 #' which is designed to process Barcode count data gained from
 #' cell clonal tracking experiments.
 #'
-#' @param object A numeric matrix of Barcode counts, with Barcodes in rows
+#' @param object A numeric `matrix` of Barcode counts, with Barcodes in rows
 #'  and samples in columns;
 #'  Alternatively, you can pass an existing `barbieQ` object, from which
-#'  barcode counts, sample conditions, and color palettes will be inherited.
-#' @param target A `matrix` or `data.frame` of sample conditions,
-#'  with each factor in a separate column.
-#'  If a `barbieQ` object is passed to `object`, the sample conditions
-#'  in `barbieQ` will be updated by `target`.
+#'  barcode counts, sample conditions, and the mapping colors will be inherited.
+#' @param target A `matrix` or `data.frame` where rows represent samples 
+#'  and columns represent factors, each containing the specific condition assigned to a sample.
 #'  If not specified, all samples are assigned the same condition.
-#' @param factorColors A `list` of colour palettes corresponding to
-#'  the factors in `target`.
-#'  If a `barbieQ` object is passed to `object`, the color palettes
-#'  in `barbieQ`will be updated by `factorColors`.
-#'  If not specified, defaults to NULL.
+#'  If a `barbieQ` object is passed to `object`, the sample conditions
+#'  will be updated by specifying `target`.
+#' @param factorColors A `list` mapping factors in `target` to color palettes, 
+#'  where each element is a named `vector` assigning colors to specific sample conditions.
+#'  If not specified, defaults to `NULL`.
+#'  If a `barbieQ` object is passed to `object`, the mapping colors
+#'  will be updated by specifying `factorColors`.
 #'
 #' @return A `barbieQ` object, including several components:
-#'  * `assay`: a `data.frame` containing Barcode counts across samples.
-#'  * `metadata`: a `data.frame` representing sample conditions,
-#'    organized by various experimental factors.
-#'  * `factorColors`: a `list` of color palettes corresponding to
-#'    the sample conditions.
+#'  * `assay`: a `data.frame` of Barcode counts, with Barcodes in rows and samples in columns.
+#'  * `metadata`: a `data.frame` of sample conditions, with samples in rows and
+#'    experimental factors in columns.
+#'  * `factorColors`: A `list` mapping factors in `target` to color palettes,
+#'    where each element is a named `vector` assigning colors to specific sample conditions.
 #'  * Matrices of `proportion`, `CPM`, `occurrence`, and `rank` representing
-#'    the proportion, Counts Per Million (CPM), presence or absence, and ranking
-#'    of Barcodes in each sample, based on the Barcode counts in `assay`.
-#'  * `isTop`: a list containing a vector `vec` and a matrix `mat`, tagging
-#'    each Barcode as being part of the major contributors or not,
-#'    by calling the function [tagTopBarcodes].
+#'    Barcode proportion, Counts Per Million (CPM), presence/absence, and ranking
+#'    in each sample, based on the Barcode counts in `assay`.
+#'  * `isTop`: a `list` containing a `vector` (`vec`) and a `matrix` (`mat`),
+#'    indicating whether each Barcode is a major contributor, determined by calling [tagTopBarcodes].
 #'  * Additional processed information for further analysis.
 #'
 #' @export
@@ -113,30 +112,28 @@ createBarbieQ <- function(object, target = NULL, factorColors = NULL) {
   ## extract metadata from `target`
   ## if `target` not specified, inherit metadata from the passed `barbieQ` object
   if (is.null(target)) target <- barbieQ$metadata
-  ## if 'barbieQ$metadata' is NULL either, assume a homogeneous setting in the metadata.
+  ## if 'barbieQ$metadata' is NULL either, default a homogeneous setting in the metadata.
   if (is.null(target)) {
     target <- as.data.frame(matrix(1, ncol(barbieQ$assay), 1))
-    message("no 'target' provided.
-now creating a pseudo uni-group with a homogeneous setting in 'barbieQ$metadata'.")
+    warning("no valid 'target' provided. Assigning a homogeneous condition to all samples.")
   } else {
-    ## now target is provided by either @param target or barbieQ$metadata, check target format
-    if (is.vector(target) || is.factor(target)) {
-      target <- matrix(target, ncol = 1)
+    ## with valid `target` provided by either @param `target` or `object$metadata`, check the structure
+    if ((!(is.list(target)) && is.vector(target)) || is.factor(target)) {
+      target <- data.frame(target)
     } else if (!(inherits(target, "data.frame") || inherits(target, "matrix"))) {
-      stop("'target' should be a vector, matrix or data.frame describing sample conditions.")
+      stop("'target' must be a vector, matrix or data.frame describing sample conditions.")
     }
   }
 
-  ## check if the sample sizes match between 'barbieQ$metadata' and 'barbieQ$assay'
+  ## check if sample size match between 'barbieQ$metadata' and 'barbieQ$assay'
   if (identical(ncol(barbieQ$assay), nrow(target))) {
     barbieQ$metadata <- as.data.frame(target)
   } else {
-    ## if sample sizes don't match, create a homogeneous setting in metadata.
+    ## if sample size not matching, set a homogeneous setting in metadata.
     barbieQ$metadata <- as.data.frame(matrix("1", ncol(barbieQ$assay), 1))
-    warning("sample size of 'target' (or 'barbieQ$metadata') doesn't match sample size of Barcode count extracted in 'object'!
-now creating a pseudo uni-group with a homogeneous setting in 'barbieQ$metadata'.")
+    warning("sample size mismatch between conditions and barcode counts! Assigning a homogeneous condition to all samples.")
   }
-  if (anyNA(barbieQ$metadata)) warning("barbieQ$metadata includes NAs.")
+  if (anyNA(barbieQ$metadata)) warning("sample conditions includes NAs.")
 
   ## extract factor color list from @param 'factorColors'
   ## if @param factorColors is not provided, inherit factorColors from the 'barbieQ' object created.
@@ -150,15 +147,20 @@ now creating a pseudo uni-group with a homogeneous setting in 'barbieQ$metadata'
 
   ## now 'barbieQ$assay' should be a matrix already, check if it's numeric apart from NAs.
   ## find NAs in the 'barbieQ$assay'
-  ColumnHasNA <- vapply(as.data.frame(barbieQ$assay), function(x) any(is.na(x)), FUN.VALUE = logical(1L))
+  ColumnHasNA <- vapply(
+    as.data.frame(barbieQ$assay), 
+    function(x) any(is.na(x)), 
+    FUN.VALUE = logical(1L)
+    )
   WhichColumnHasNA <- which(ColumnHasNA)
-  RowHasNA <- vapply(seq_len(nrow(barbieQ$assay)),
+  RowHasNA <- vapply(
+    seq_len(nrow(barbieQ$assay)),
     function(i) any(is.na(barbieQ$assay[i, ])),
     FUN.VALUE = logical(1L)
   )
   WhichRowHasNA <- which(RowHasNA)
   if (any(ColumnHasNA)) {
-    warning("In Barcode count matrix (barbieQ$assay), ", length(WhichRowHasNA), " Barcodes (rows) show NAs across ", length(WhichColumnHasNA), " samples (columns).")
+    warning("Barcode count matrix has NA, across ", length(WhichRowHasNA), " Barcodes (rows), and ", length(WhichColumnHasNA), " samples (columns).")
     ## display a menu for the user to choose how to handle NAs.
     choice <- utils::menu(c("yes, continue with zeros", "no, keep NA and continue", "stop"), title = "Do you want to convert all NA into zero and continue?")
     if (choice == 1) {
@@ -167,10 +169,9 @@ now creating a pseudo uni-group with a homogeneous setting in 'barbieQ$metadata'
       message("all NAs in Barcode count table are converted into zero.")
     } else if (choice == 2) {
       ## proceed without preprocessing calculations
-      message("NAs are retained. barbieQ object is created without preprocessing.
-note that NAs may cause issues in subsequent analyses.")
+      message("NAs are retained. barbieQ object is created without auto-preprocessing. Note that NAs may cause issues in subsequent analyses.")
     } else {
-      stop("please address the NAs in the 'object' parameter first.")
+      stop("please address the NAs in the barcode count matrix first.")
     }
   }
 

R/tagTopBarcodes.R

@@ -1,22 +1,24 @@
 #' Tag each Barcode as being part of the major contributors or not
 #'
-#' `tagTopBarcodes()` is designed for better filtering out the background noise,
-#'  i.e., Barcodes that consistently have low contributions across samples.
-#'  Each Barcode is tagged as one of the major contributing Barcodes
-#'  (\emph{top} Barcodes) or not in each sample, based on whether their
+#' `tagTopBarcodes()` tags \emph{top} Barcodes that collectively contribute to 
+#'  the majority of counts across the dataset.
+#'  It is designed for subsequently filtering out the background noise,
+#'  i.e., filtering out Barcodes that consistently have low contributions across samples.
+#'  In each sample, Barcodes are tagged as major contributing Barcodes
+#'  (\emph{top} Barcodes) or not, based on whether their
 #'  combined proportion passes a defined threshold in the sample.
 #'  Across the entire dataset, a Barcode is considered \emph{top}
 #'  if it is tagged as \emph{top} in a number of samples,
 #'  meeting a specified appearance threshold across all selected samples.
 #'
 #' @param barbieQ An object created by the [createBarbieQ] function.
-#' @param activeSamples a logical vector indicating which samples (columns)
+#' @param activeSamples A logical vector indicating which samples (columns)
 #'  to consider when determining the \emph{top} Barcodes across the entire
 #'  dataset. Default to considering all samples in the `barbieQ` object.
 #' @param proportionThreshold A numeric value ranging from 0 to 1,
 #'  used as a threshold for determining \emph{top} Barcodes in each sample
 #'  based on their combined proportion in theat sample. Default to 0.99.
-#' @param minTopFrequency An integer specifying the minimum number of times
+#' @param nSampleThreshold An integer specifying the minimum number of times
 #'  a Barcode must be tagged as \emph{top} across the selected samples
 #'  (specified by `activeSamples`) in order to be considered \emph{top}
 #'  for the entire dataset. Default to 1.
@@ -52,7 +54,7 @@
 #' ## tag top Barcodes
 #' tagTopBarcodes(myBarbieQ)
 tagTopBarcodes <- function(barbieQ, activeSamples = NULL,
-                           proportionThreshold = 0.99, minTopFrequency = 1) {
+                           proportionThreshold = 0.99, nSampleThreshold = 1) {
   mat <- barbieQ$assay
   ## dispatch 'returnNumMat' function to ensure the object is a numeric matrix apart from NAs.
   if (inherits(mat, "data.frame") || inherits(mat, "matrix") || is.vector(mat)) {
@@ -69,7 +71,7 @@ tagTopBarcodes <- function(barbieQ, activeSamples = NULL,
   ## select the active columns used to determine 'top Barcodes' out of the samples.
   subTopMat <- topsInMat[, activeSamples, drop = FALSE]
   ## determine the 'top Barcodes' based on the numbers of being true out of all 'active' samples.
-  topOverall <- rowSums(subTopMat, na.rm = TRUE) >= minTopFrequency
+  topOverall <- rowSums(subTopMat, na.rm = TRUE) >= nSampleThreshold
   ## store
   updatedObject <- list(
     ## retain other components
@@ -101,7 +103,7 @@ tagTopBarcodes <- function(barbieQ, activeSamples = NULL,
 
 #' Tag \emph{top} Barcodes in each sample.
 #'
-#' @param tempCol a numeric vector of Barcode counts in a sample,
+#' @param tempCol A numeric vector of Barcode counts in a sample,
 #'  usually being a column in a count matrix
 #' @param proportionThreshold A numeric value ranging from 0 to 1,
 #'  used as a threshold for determining \emph{top} Barcodes in each sample

tests/testthat/test-tagTopBarcodes.R

@@ -35,10 +35,10 @@ test_that("tagging top Barcodes across samples works", {
     proportionThreshold = 0.5
   )
   expect_equal(object4$isTop$vec, rep(c(TRUE, FALSE), each = 25))
-  ## check `minTopFrequency` setting up correct minimum frequency of *top*
+  ## check `nSampleThreshold` setting up correct minimum frequency of *top*
   object5 <- tagTopBarcodes(
     barbieQ = object1, activeSamples = rep(c(TRUE, FALSE), each = 6),
-    proportionThreshold = 0.5, minTopFrequency = 2
+    proportionThreshold = 0.5, nSampleThreshold = 2
   )
   expect_equal(object5$isTop$vec, rep(FALSE, 50))
 })