Rename subsampleCounts to rarefyAssay (microbiome#536)

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

Hide file tree

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

diff --git a/NAMESPACE b/NAMESPACE
@@ -87,6 +87,7 @@ export(perSampleDominantFeatures)
 export(perSampleDominantTaxa)
 export(performDMNgroupCV)
 export(plotNMDS)
+export(rarefyAssay)
 export(readQZA)
 export(relAbundanceCounts)
 export(relabundance)
@@ -197,6 +198,7 @@ exportMethods(mergeSamples)
 exportMethods(perSampleDominantFeatures)
 exportMethods(perSampleDominantTaxa)
 exportMethods(performDMNgroupCV)
+exportMethods(rarefyAssay)
 exportMethods(relAbundanceCounts)
 exportMethods(relabundance)
 exportMethods(right_join)

diff --git a/NEWS b/NEWS
@@ -127,3 +127,4 @@ Changes in version 1.13.x
   relAbundanceCounts
 + rename getRare* functions to getRare, getUnique* functions to getUnique, 
   getTop* functions to getTop and getPrevalent* functions to getPrevalent
++ Rename subsampleCounts to rarefyAssay
diff --git a/R/deprecate.R b/R/deprecate.R
@@ -821,3 +821,21 @@ setMethod(
         getPrevalent(x,...)
     }
 )
+
+#' @rdname deprecate
+#' @export
+setGeneric(
+    "subsampleCounts", signature = c("x"), function(x, ...)
+        standardGeneric("subsampleCounts"))
+
+#' @rdname deprecate
+#' @export
+setMethod(
+    "subsampleCounts", signature = c(x = "SummarizedExperiment"),
+    function(x, ...){
+        .Deprecated(
+            msg = "'subsampleCounts' is deprecated. ",
+            "Use 'rarefyAssay' instead.")
+        rarefyAssay(x, ...)
+    }
+)
diff --git a/R/subsampleCounts.R → R/rarefyAssay.R b/R/subsampleCounts.R → R/rarefyAssay.R
@@ -1,14 +1,14 @@
 #' Subsample Counts
 #' 
-#' \code{subsampleCounts} will randomly subsample counts in 
+#' \code{rarefyAssay} will randomly subsample counts in 
 #' \code{SummarizedExperiment} and return the a modified object in which each 
 #' sample has same number of total observations/counts/reads. 
 #'
 #' @details
 #' Although the subsampling approach is highly debated in microbiome research, 
-#' we include the \code{subsampleCounts} function because there may be some 
+#' we include the \code{rarefyAssay} function because there may be some 
 #' instances where it can be useful.
-#' Note that the output of \code{subsampleCounts} is not the equivalent as the 
+#' Note that the output of \code{rarefyAssay} is not the equivalent as the 
 #' input and any result have to be verified with the original dataset.
 #' To maintain the reproducibility, please define the seed using set.seed() 
 #' before implement this function.
@@ -58,11 +58,11 @@
 #' microbial differential abundance strategies depend upon data characteristics. 
 #' Microbiome. 2017 Dec;5(1):1-8.
 #' 
-#' @return \code{subsampleCounts} return \code{x} with subsampled data.
+#' @return \code{rarefyAssay} return \code{x} with subsampled data.
 #' 
 #' @author Sudarshan A. Shetty and Felix G.M. Ernst
 #' 
-#' @name subsampleCounts
+#' @name rarefyAssay
 #'  
 #' @examples
 #' # When samples in TreeSE are less than specified min_size, they will be removed.
@@ -71,7 +71,7 @@
 #' data(GlobalPatterns)
 #' tse <- GlobalPatterns
 #' set.seed(123)
-#' tse.subsampled <- subsampleCounts(tse, 
+#' tse.subsampled <- rarefyAssay(tse, 
 #'                                   min_size = 60000, 
 #'                                   name = "subsampled" 
 #'                                   )
@@ -81,22 +81,20 @@
 #' 
 NULL
 
-#' @rdname subsampleCounts
-#' @aliases rarifyCounts
+#' @rdname rarefyAssay
 #' @export
-setGeneric("subsampleCounts", signature = c("x"),
+setGeneric("rarefyAssay", signature = c("x"),
            function(x, assay.type = assay_name, assay_name = "counts", 
                     min_size = min(colSums2(assay(x))),
                     replace = TRUE,
                     name = "subsampled", verbose = TRUE, ...)
-               standardGeneric("subsampleCounts"))
+               standardGeneric("rarefyAssay"))
 
 #' @importFrom SummarizedExperiment assay assay<-
 #' @importFrom DelayedMatrixStats colSums2 rowSums2
-#' @rdname subsampleCounts
-#' @aliases rarifyCounts
+#' @rdname rarefyAssay
 #' @export
-setMethod("subsampleCounts", signature = c(x = "SummarizedExperiment"),
+setMethod("rarefyAssay", signature = c(x = "SummarizedExperiment"),
           function(x, assay.type = assay_name, assay_name = "counts", 
                    min_size = min(colSums2(assay(x))),
                     replace = TRUE, 

diff --git a/man/deprecate.Rd b/man/deprecate.Rd
diff --git a/man/subsampleCounts.Rd → man/rarefyAssay.Rd b/man/subsampleCounts.Rd → man/rarefyAssay.Rd
diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml
@@ -67,7 +67,7 @@ reference:
 - contents:
   - meltSE
   - relabundance
-  - subsampleCounts
+  - rarefyAssay
   - subsetSamples
 - subtitle: Datasets
 - contents:

diff --git a/tests/testthat/test-8subsample.R b/tests/testthat/test-8subsample.R
@@ -1,10 +1,10 @@
-context("subsampleCounts")
-test_that("subsampleCounts", {
+context("rarefyAssay")
+test_that("rarefyAssay", {
     seed = 1938
     set.seed(seed)
     data(GlobalPatterns, package="mia")
 
-    expect_warning(tse.subsampled <- subsampleCounts(GlobalPatterns, 
+    expect_warning(tse.subsampled <- rarefyAssay(GlobalPatterns, 
                                                      min_size = 60000, 
                                                      name = "subsampled",
                                                      replace = TRUE))
@@ -37,7 +37,7 @@ test_that("subsampleCounts", {
     # When replace = FALSE
     seed = 1938
     set.seed(seed)
-    expect_warning(tse.subsampled.rp <- subsampleCounts(GlobalPatterns, 
+    expect_warning(tse.subsampled.rp <- rarefyAssay(GlobalPatterns, 
                                                         min_size = 60000, 
                                                         name = "subsampled",
                                                         replace = FALSE))

diff --git a/tests/testthat/test-9cluster.R b/tests/testthat/test-9cluster.R
@@ -1,5 +1,5 @@
-context("subsampleCounts")
-test_that("subsampleCounts", {
+context("rarefyAssay")
+test_that("rarefyAssay", {
     library(bluster)
     data(GlobalPatterns, package="mia")
 

diff --git a/vignettes/mia.Rmd b/vignettes/mia.Rmd
@@ -193,7 +193,7 @@ Sub-sampling to equal number of counts per sample. Also known as rarefying.
 ```{r}
 data(GlobalPatterns, package = "mia")
 
-tse.subsampled <- subsampleCounts(GlobalPatterns, 
+tse.subsampled <- rarefyAssay(GlobalPatterns, 
                                   min_size = 60000, 
                                   name = "subsampled",
                                   replace = TRUE,