Add rank support to getTop

R/AllGenerics.R

@@ -270,8 +270,9 @@ setGeneric("getUnique", signature = c("x"), function(x, ...)
 #' @export
 setGeneric("getTop", signature = "x",
     function(
-        x, top= 5L, method = c("mean", "sum", "median"),
-        assay.type = assay_name, assay_name = "counts", na.rm = TRUE, ...)
+        x, top= 5L, method = c("mean", "sum", "median", "prevalence"),
+        assay.type = assay_name, assay_name = "counts", rank = NULL,
+        na.rm = TRUE, ...)
     standardGeneric("getTop"))
 
 #' @rdname taxonomy-methods

R/summaries.R

@@ -11,6 +11,11 @@
 #' @param method \code{Character scalar}. Specify the method to determine top
 #' taxa. Either sum, mean, median or prevalence. (Default: \code{"mean"})
 #'
+#' @param rank \code{Character scalar}. Defines a taxonomic rank. When
+#'   provided, input is first aggregated with \code{agglomerateByRank()} at the
+#'   given rank before selecting top features. Must be one of
+#'   \code{taxonomyRanks(x)}. (Default: \code{NULL}).
+#'
 #' @param ... Additional arguments passed, e.g., to getPrevalence:
 #'    \itemize{
 #'        \item \code{sort}: \code{Logical scalar}. Specify
@@ -106,32 +111,39 @@ NULL
 setMethod("getTop", signature = c(x = "SummarizedExperiment"),
     function(
         x, top = 5L, method = c("mean", "sum", "median", "prevalence"),
-        assay.type = assay_name, assay_name = "counts", 
+        assay.type = assay_name, assay_name = "counts", rank = NULL,
         na.rm = TRUE, ...){
+        dots <- list(...)
         # input check
         method <- match.arg(method, c("mean","sum","median","prevalence"))
+        if (!is.null(rank)) {
+            .check_taxonomic_rank(rank, x)
+            x <- agglomerateByRank(x, rank = rank)
+        }
         # check max taxa
         .check_max_taxa(x, top, assay.type)
         # check assay
         .check_assay_present(assay.type, x)
         #
         if(method == "prevalence"){
-            taxs <- getPrevalence(
-                assay(x, assay.type), sort = TRUE, include.lowest = TRUE, ...)
+            taxs <- do.call(
+                getPrevalence,
+                c(list(assay(x, assay.type), sort = TRUE, include.lowest = TRUE),
+                  dots))
             # If there are taxa with prevalence of 0, remove them
             taxs <- taxs[ taxs > 0 ]
         } else {
             taxs <- switch(
                 method,
                 mean = rowMeans2(assay(x, assay.type), na.rm = na.rm),
                 sum = rowSums2(assay(x, assay.type), na.rm = na.rm),
-                median = rowMedians(assay(x, assay.type)), na.rm = na.rm)
+                median = rowMedians(assay(x, assay.type), na.rm = na.rm))
             names(taxs) <- rownames(assay(x))
             taxs <- sort(taxs,decreasing = TRUE)
         }
         names <- head(names(taxs), n = top)
         # Remove NAs and sort if specified
-        names <- .remove_NAs_and_sort(names, ... )
+        names <- do.call(.remove_NAs_and_sort, c(list(names), dots))
         return(names)
     }
 )

tests/testthat/test-8summaries.R

@@ -60,4 +60,12 @@ test_that("summaries", {
     # Test with multiple equal dominant taxa in one sample
     assay(GlobalPatterns)[1, 1] <- max(assay(GlobalPatterns)[, 1])
     expect_warning(summarizeDominance(GlobalPatterns, complete = FALSE))
+
+    # getTop with rank aggregation matches explicit agglomeration
+    agg <- agglomerateByRank(GlobalPatterns, rank = "Genus")
+    expect_identical(
+        getTop(GlobalPatterns, rank = "Genus", method = "mean", top = 5,
+               assay.type = "counts"),
+        getTop(agg, method = "mean", top = 5, assay.type = "counts")
+    )
 })