Rename countDominant* functions to summarizeDominance (microbiome#528)

Co-authored-by: Tuomas Borman <[email protected]> Co-authored-by: TuomasBorman <[email protected]>
Daenarys8 · May 20, 2024 · 9e4d0dc · 9e4d0dc
1 parent f637dae
commit 9e4d0dc
Show file tree

Hide file tree

Showing 9 changed files with 79 additions and 58 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: mia
 Type: Package
-Version: 1.13.7
+Version: 1.13.8
 Authors@R:
     c(person(given = "Felix G.M.", family = "Ernst", role = c("aut"),
              email = "[email protected]",

diff --git a/NAMESPACE b/NAMESPACE
@@ -104,6 +104,7 @@ export(subsetByRareTaxa)
 export(subsetFeatures)
 export(subsetSamples)
 export(subsetTaxa)
+export(summarizeDominance)
 export(taxonomyTree)
 export(testExperimentCrossAssociation)
 export(testExperimentCrossCorrelation)
@@ -202,6 +203,7 @@ exportMethods(subsetByRareTaxa)
 exportMethods(subsetFeatures)
 exportMethods(subsetSamples)
 exportMethods(subsetTaxa)
+exportMethods(summarizeDominance)
 exportMethods(summary)
 exportMethods(taxonomyRankEmpty)
 exportMethods(taxonomyRanks)

diff --git a/NEWS b/NEWS
@@ -121,3 +121,4 @@ Changes in version 1.13.x
 + getHierarchyTree: bugfix related to empty cells in rowData
 + agglomerateByRank: bugfix: trees was not pruned correctly
 + rename meltAssay to meltSE
++ Rename countDominantFeatures and countDominantTaxa to summarizeDominance
diff --git a/R/deprecate.R b/R/deprecate.R
@@ -362,6 +362,38 @@ loadFromHumann <- function(...) {
     importHUMAnN(...)
 }
 
+#' @rdname deprecate
+#' @export
+setGeneric("countDominantFeatures", signature = c("x"),
+            function(x, ...)
+                standardGeneric("countDominantFeatures"))
+
+#' @rdname deprecate
+#' @export
+setMethod("countDominantFeatures", signature = c(x = "SummarizedExperiment"),
+            function(x, ...){
+                .Deprecated(msg = "'countDominantFeatures' function is deprecated. ",
+                            "Use 'summarizeDominance' instead.")
+                summarizeDominance(x, ...)
+            }
+)
+
+#' @rdname deprecate
+#' @export
+setGeneric("countDominantTaxa", signature = c("x"),
+           function(x, ...)
+               standardGeneric("countDominantTaxa"))
+
+#' @rdname deprecate
+#' @export
+setMethod("countDominantTaxa", signature = c(x = "SummarizedExperiment"),
+          function(x, ...){
+              .Deprecated(msg = "'countDominantTaxa' function is deprecated. ",
+                          "Use 'summarizeDominance' instead.")
+              summarizeDominance(x, ...)
+          }
+)
+
 #' @rdname deprecate
 #' @export
 setGeneric("full_join", signature = c("x"),

diff --git a/R/summaries.R b/R/summaries.R
@@ -78,13 +78,13 @@
 #'                              na.rm = TRUE))
 #'
 #' # Gets the overview of dominant taxa
-#' dominant_taxa <- countDominantFeatures(GlobalPatterns,
+#' dominant_taxa <- summarizeDominance(GlobalPatterns,
 #'                                    rank = "Genus")
 #' dominant_taxa
 #'
 #' # With group, it is possible to group observations based on specified groups
 #' # Gets the overview of dominant taxa
-#' dominant_taxa <- countDominantFeatures(GlobalPatterns,
+#' dominant_taxa <- summarizeDominance(GlobalPatterns,
 #'                                    rank = "Genus",
 #'                                    group = "SampleType",
 #'                                    na.rm = TRUE)
@@ -231,29 +231,28 @@ setMethod("getUniqueTaxa", signature = c(x = "SummarizedExperiment"),
 #' @param name The column name for the features. The default is 'dominant_taxa'.
 #'
 #' @param ... Additional arguments passed on to \code{agglomerateByRank()} when
-#'   \code{rank} is specified for \code{countDominantFeatures}.
+#'   \code{rank} is specified for \code{summarizeDominance}.
 #'
 #'
 #' @details
-#' \code{countDominantFeatures} returns information about most dominant
+#' \code{summarizeDominance} returns information about most dominant
 #' taxa in a tibble. Information includes their absolute and relative
 #' abundances in whole data set.
 #'
 #'
 #' @return
-#' The \code{countDominantFeatures} returns an overview in a tibble. It contains dominant taxa
+#' The \code{summarizeDominance} returns an overview in a tibble. It contains dominant taxa
 #' in a column named \code{*name*} and its abundance in the data set.
 #' 
 #' @export
-setGeneric("countDominantFeatures",signature = c("x"),
+setGeneric("summarizeDominance",signature = c("x"),
            function(x, group = NULL, name = "dominant_taxa", ...)
-               standardGeneric("countDominantFeatures"))
+               standardGeneric("summarizeDominance"))
 
 
 #' @rdname summaries
-#' @aliases countDominantTaxa
 #' @export
-setMethod("countDominantFeatures", signature = c(x = "SummarizedExperiment"),
+setMethod("summarizeDominance", signature = c(x = "SummarizedExperiment"),
     function(x, group = NULL, name = "dominant_taxa", ...){
         # Input check
         # group check
@@ -294,25 +293,6 @@ setMethod("countDominantFeatures", signature = c(x = "SummarizedExperiment"),
     }
 )
 
-
-#' @rdname summaries
-#' @aliases countDominantFeatures
-#' @export
-setGeneric("countDominantTaxa", signature = c("x"),
-           function(x, ...)
-               standardGeneric("countDominantTaxa"))
-
-#' @rdname summaries
-#' @aliases countDominantFeatures
-#' @export
-setMethod("countDominantTaxa", signature = c(x = "SummarizedExperiment"),
-    function(x, ...){
-        .Deprecated(old ="countDominantTaxa", new = "countDominantFeatures", msg = "The 'countDominantTaxa' function is deprecated. Use 'countDominantFeatures' instead.")
-        countDominantFeatures(x, ...)
-    }
-)
-
-
 ################################ HELP FUNCTIONS ################################
 
 #' @importFrom S4Vectors as.data.frame

diff --git a/man/deprecate.Rd b/man/deprecate.Rd
diff --git a/man/summaries.Rd b/man/summaries.Rd
diff --git a/tests/testthat/test-5dominantTaxa.R b/tests/testthat/test-5dominantTaxa.R
@@ -79,24 +79,24 @@ test_that("perSampleDominantFeatures", {
     test_perSampleDominantFeatures(GlobalPatterns)
 
 
-    test_that("countDominantFeatures", {
+    test_that("summarizeDominance", {
 
-        test_countDominantFeatures <- function(tse){
-            expect_equal(countDominantFeatures(tse, group = "SampleType")$dominant_taxa,
+        test_summarizeDominance <- function(tse){
+            expect_equal(summarizeDominance(tse, group = "SampleType")$dominant_taxa,
                          c("331820", "549656", "550960", "319044", "189047",
                            "279599", "329744", "12812",  "534609", "557211",
                            "87194", "484436", "64396", "98605", "256977",
                            "36155","71074",  "114821", "360229"))
 
-            expect_equal(countDominantFeatures(tse,
+            expect_equal(summarizeDominance(tse,
                                            rank = "Kingdom")$dominant_taxa[1],
                          c("Bacteria"))
 
-            expect_equal(countDominantFeatures(tse, rank = "Order", digits = 3)$rel_freq,
+            expect_equal(summarizeDominance(tse, rank = "Order", digits = 3)$rel_freq,
                          c(0.231, 0.115, 0.077, 0.077, 0.077, 0.077, 0.038, 0.038, 0.038, 0.038, 0.038, 0.038, 0.038, 0.038, 0.038))
 
             # check sample type
-            sample.type <- countDominantFeatures(tse, rank = "Class",
+            sample.type <- summarizeDominance(tse, rank = "Class",
                                              group = "SampleType")$SampleType
 
             expect_equal(as.character(sample.type),
@@ -109,8 +109,8 @@ test_that("perSampleDominantFeatures", {
             assay(tse1)[1, 1] <- max(assay(tse1)[, 1])
 
             # Calculate info about dominant taxa
-            count_dominant <- countDominantFeatures(tse)
-            count_dominant1 <- countDominantFeatures(tse1)
+            count_dominant <- summarizeDominance(tse)
+            count_dominant1 <- summarizeDominance(tse1)
 
             # count_dominant1 should have one extra row, since there are more dominant taxa
             expect_equal( nrow(count_dominant1), nrow(count_dominant) + 1)
@@ -120,16 +120,16 @@ test_that("perSampleDominantFeatures", {
             expect_true(count_dominant$dominant_taxa[1] %in% count_dominant1$dominant_taxa)
 
             # Now the row lengths should be equal
-            count_dominant <- countDominantFeatures(tse, complete = F)
-            expect_warning(count_dominant1 <- countDominantFeatures(tse1, complete = F))
+            count_dominant <- summarizeDominance(tse, complete = F)
+            expect_warning(count_dominant1 <- summarizeDominance(tse1, complete = F))
 
             expect_equal(nrow(count_dominant1), nrow(count_dominant))
 
         }
 
         # TSE object
         data(GlobalPatterns, package="mia")
-        test_countDominantFeatures(GlobalPatterns)
+        test_summarizeDominance(GlobalPatterns)
 
     })
 })

diff --git a/tests/testthat/test-8summaries.R b/tests/testthat/test-8summaries.R
@@ -55,10 +55,10 @@ test_that("summaries", {
                                  assay.type = "counts") )
     expect_equal( getUniqueTaxa(GlobalPatterns, "Phylum", sort = TRUE),
                   getUniqueFeatures(GlobalPatterns, "Phylum", sort = TRUE) )
-    expect_equal( countDominantTaxa(GlobalPatterns),
-                  countDominantFeatures(GlobalPatterns))
+    expect_equal( summarizeDominance(GlobalPatterns),
+                  summarizeDominance(GlobalPatterns))
 
     # Test with multiple equal dominant taxa in one sample
     assay(GlobalPatterns)[1, 1] <- max(assay(GlobalPatterns)[, 1])
-    expect_warning(countDominantFeatures(GlobalPatterns, complete = FALSE))
+    expect_warning(summarizeDominance(GlobalPatterns, complete = FALSE))
 })