Rename perSampleDominant* to getDominant and addPerSampleDominant* to…

… addDominant (microbiome#527)

Co-authored-by: TuomasBorman <tvborm@utu.fi>

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: mia
 Type: Package
-Version: 1.13.13
+Version: 1.13.14
 Authors@R:
     c(person(given = "Felix G.M.", family = "Ernst", role = c("aut"),
              email = "felix.gm.ernst@outlook.com",

NAMESPACE

@@ -6,6 +6,7 @@ export(ZTransform)
 export(addCluster)
 export(addContaminantQC)
 export(addDivergence)
+export(addDominant)
 export(addMediation)
 export(addNotContaminantQC)
 export(addPerSampleDominantFeatures)
@@ -35,6 +36,7 @@ export(full_join)
 export(getBestDMNFit)
 export(getCrossAssociation)
 export(getDMN)
+export(getDominant)
 export(getExperimentCrossAssociation)
 export(getExperimentCrossCorrelation)
 export(getMediation)
@@ -126,6 +128,7 @@ exportMethods(ZTransform)
 exportMethods(addCluster)
 exportMethods(addContaminantQC)
 exportMethods(addDivergence)
+exportMethods(addDominant)
 exportMethods(addHierarchyTree)
 exportMethods(addMediation)
 exportMethods(addNotContaminantQC)
@@ -159,6 +162,7 @@ exportMethods(full_join)
 exportMethods(getBestDMNFit)
 exportMethods(getCrossAssociation)
 exportMethods(getDMN)
+exportMethods(getDominant)
 exportMethods(getExperimentCrossAssociation)
 exportMethods(getExperimentCrossCorrelation)
 exportMethods(getHierarchyTree)

NEWS

@@ -128,3 +128,5 @@ Changes in version 1.13.x
 + rename getRare* functions to getRare, getUnique* functions to getUnique, 
   getTop* functions to getTop and getPrevalent* functions to getPrevalent
 + Rename subsampleCounts to rarefyAssay
++ Rename perSampleDominant* functions to getDominant and addPerSampleDominant* 
+  functions to addDominant

R/deprecate.R

@@ -514,7 +514,7 @@ setMethod("left_join", signature = c(x = "ANY"),
 )
 
 #' @rdname deprecate
-#' @export
+#' @export            
 setGeneric("right_join", signature = c("x"),
            function(x, ...)
                standardGeneric("right_join"))
@@ -839,3 +839,75 @@ setMethod(
         rarefyAssay(x, ...)
     }
 )
+
+#' @rdname deprecate
+#' @export
+setGeneric(
+    "addPerSampleDominantFeatures", signature = c("x"), function(x, ...) 
+        standardGeneric("addPerSampleDominantFeatures"))
+
+#' @rdname deprecate
+#' @export
+setMethod(
+    "addPerSampleDominantFeatures", signature = c(x = "SummarizedExperiment"),
+    function(x, ...){
+        .Deprecated(
+            msg = "'addPerSampleDominantFeatures' is deprecated.",
+            " Use 'addDominant' instead.")
+        addDominant(x, ...)
+    }
+)
+
+#' @rdname deprecate
+#' @export
+setGeneric(
+    "addPerSampleDominantTaxa", signature = c("x"), function(x, ...) 
+        standardGeneric("addPerSampleDominantTaxa"))
+
+#' @rdname deprecate
+#' @export
+setMethod(
+    "addPerSampleDominantTaxa", signature = c(x = "SummarizedExperiment"),
+    function(x, ...){
+        .Deprecated(
+            msg = "'addPerSampleDominantTaxa' is deprecated. ",
+            "Use 'addDominant' instead.")
+        addDominant(x, ...)
+    }
+)
+
+#' @rdname deprecate
+#' @export
+setGeneric(
+    "perSampleDominantFeatures", signature = c("x"), function(x, ...) 
+        standardGeneric("perSampleDominantFeatures"))
+
+#' @rdname deprecate
+#' @export
+setMethod(
+    "perSampleDominantFeatures", signature = c(x = "SummarizedExperiment"),
+    function(x, ...){
+        .Deprecated(
+            msg = "'perSampleDominantFeatures' is deprecated. ",
+            "Use 'getDominant' instead.")
+        getDominant(x, ...)
+    }
+)
+
+#' @rdname deprecate
+#' @export
+setGeneric(
+    "perSampleDominantTaxa", signature = c("x"), function(x, ...) 
+        standardGeneric("perSampleDominantTaxa"))
+
+#' @rdname deprecate
+#' @export
+setMethod(
+    "perSampleDominantTaxa", signature = c(x = "SummarizedExperiment"),
+    function(x, ...){
+        .Deprecated(
+            msg = "'perSampleDominantTaxa' is deprecated. ",
+            "Use 'getDominant' instead.")
+        getDominant(x, ...)
+    }
+)

R/dominantTaxa.R → R/getDominant.R

@@ -21,7 +21,7 @@
 #'   the output of \code{taxonomyRanks()}.
 #'
 #' @param name A name for the column of the \code{colData} where the dominant
-#'   taxa will be stored in when using \code{addPerSampleDominantFeatures}.
+#'   taxa will be stored in when using \code{addDominant}.
 #'   
 #' @param other.name A name for features that are not included in n the most frequent 
 #' dominant features in the data. Default is "Other".
@@ -30,33 +30,33 @@
 #' Default is NULL, which defaults that each sample is assigned a dominant taxon.
 #' 
 #' @param complete A boolean value to manage multiple dominant taxa for a sample.
-#' Default for perSampleDominantTaxa is TRUE to include all equally dominant taxa
+#' Default for getDominant is TRUE to include all equally dominant taxa
 #' for each sample. complete = FALSE samples one taxa for the samples that have 
 #' multiple. 
-#' Default for addPerSampleDominantTaxa is FALSE to add a column with only one 
+#' Default for addDominant is FALSE to add a column with only one 
 #' dominant taxon assigned for each sample into colData. complete = TRUE adds a
 #' list that includes all dominant taxa for each sample into colData.
 #'
 #' @param ... Additional arguments passed on to \code{agglomerateByRank()} when
 #' \code{rank} is specified.
 #'
 #' @details
-#' \code{addPerSampleDominantFeatures} extracts the most abundant taxa in a
+#' \code{addDominant} extracts the most abundant taxa in a
 #' \code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}}
 #' object, and stores the information in the \code{colData}. It is a wrapper for
-#' \code{perSampleDominantFeatures}.
+#' \code{getDominant}.
 #'
 #' With \code{rank} parameter, it is possible to agglomerate taxa based on taxonomic
 #' ranks. E.g. if 'Genus' rank is used, all abundances of same Genus are added
 #' together, and those families are returned. See \code{agglomerateByRank()} for
 #' additional arguments to deal with missing values or special characters.
 #'
-#' @return \code{perSampleDominantFeatures} returns a named character vector \code{x}
-#' while \code{addPerSampleDominantFeatures} returns
+#' @return \code{getDominant} returns a named character vector \code{x}
+#' while \code{addDominant} returns
 #' \code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}}
 #' with additional column in \code{\link{colData}} named \code{*name*}.
 #'
-#' @name perSampleDominantTaxa
+#' @name getDominant
 #' @export
 #'
 #' @author Leo Lahti, Tuomas Borman and Sudarshan A. Shetty.
@@ -66,27 +66,25 @@
 #' x <- GlobalPatterns
 #'
 #' # Finds the dominant taxa.
-#' sim.dom <- perSampleDominantFeatures(x, rank="Genus")
+#' sim.dom <- getDominant(x, rank="Genus")
 #'
 #' # Add information to colData
-#' x <- addPerSampleDominantFeatures(x, rank = "Genus", name="dominant_genera")
+#' x <- addDominant(x, rank = "Genus", name="dominant_genera")
 #' colData(x)
 NULL
 
-#' @rdname perSampleDominantTaxa
-#' @aliases perSampleDominantTaxa
+#' @rdname getDominant
 #' @export
-setGeneric("perSampleDominantFeatures",signature = c("x"),
+setGeneric("getDominant",signature = c("x"),
            function(x, assay.type = assay_name, assay_name = "counts", 
                     rank = NULL, other.name = "Other", n = NULL, 
                     complete = TRUE, ...)
-               standardGeneric("perSampleDominantFeatures"))
+               standardGeneric("getDominant"))
 
-#' @rdname perSampleDominantTaxa
-#' @aliases perSampleDominantTaxa
+#' @rdname getDominant
 #' @importFrom IRanges relist
 #' @export
-setMethod("perSampleDominantFeatures", signature = c(x = "SummarizedExperiment"),
+setMethod("getDominant", signature = c(x = "SummarizedExperiment"),
     function(x, assay.type = assay_name, assay_name = "counts", 
              rank = NULL, other.name = "Other", n = NULL, complete = TRUE, ...){
         # Input check
@@ -166,36 +164,15 @@ setMethod("perSampleDominantFeatures", signature = c(x = "SummarizedExperiment")
     }
 )
 
-#' @rdname perSampleDominantTaxa
-#' @aliases perSampleDominantFeatures
+#' @rdname getDominant
 #' @export
-setGeneric("perSampleDominantTaxa", signature = c("x"),
-        function(x, ...) 
-            standardGeneric("perSampleDominantTaxa"))
-
-#' @rdname perSampleDominantTaxa
-#' @aliases perSampleDominantFeatures
-#' @export
-setMethod("perSampleDominantTaxa", signature = c(x = "SummarizedExperiment"),
-        function(x, ...){
-            .Deprecated(old ="perSampleDominantTaxa", 
-                        new = "perSampleDominantFeatures", 
-                        msg = "The 'perSampleDominantTaxa' function is deprecated. Use 'perSampleDominantFeatures' instead.")
-            perSampleDominantFeatures(x, ...)
-        }
-)
-
-#' @rdname perSampleDominantTaxa
-#' @aliases addPerSampleDominantTaxa
-#' @export
-setGeneric("addPerSampleDominantFeatures", signature = c("x"),
+setGeneric("addDominant", signature = c("x"),
            function(x, name = "dominant_taxa", other.name = "Other", n = NULL, ...)
-               standardGeneric("addPerSampleDominantFeatures"))
+               standardGeneric("addDominant"))
 
-#' @rdname perSampleDominantTaxa
-#' @aliases addPerSampleDominantTaxa
+#' @rdname getDominant
 #' @export
-setMethod("addPerSampleDominantFeatures", signature = c(x = "SummarizedExperiment"),
+setMethod("addDominant", signature = c(x = "SummarizedExperiment"),
     function(x, name = "dominant_taxa", other.name = "Other", n = NULL, 
              complete = FALSE, ...) {
         # name check
@@ -208,7 +185,7 @@ setMethod("addPerSampleDominantFeatures", signature = c(x = "SummarizedExperimen
             stop("'other.name' must be a non-empty single character value.",
                  call. = FALSE)
         }
-        dom.taxa <- perSampleDominantFeatures(x, other.name = other.name, n = n, 
+        dom.taxa <- getDominant(x, other.name = other.name, n = n, 
                                               complete = complete, ...)
         # Add list into colData if there are multiple dominant taxa
         if(length(unique(names(dom.taxa))) < length(names(dom.taxa))) {
@@ -225,26 +202,6 @@ setMethod("addPerSampleDominantFeatures", signature = c(x = "SummarizedExperimen
     }
 )
 
-#' @rdname perSampleDominantTaxa
-#' @aliases addPerSampleDominantFeatures
-#' @export
-setGeneric("addPerSampleDominantTaxa", signature = c("x"),
-        function(x, ...) 
-            standardGeneric("addPerSampleDominantTaxa"))
-
-#' @rdname perSampleDominantTaxa
-#' @aliases addPerSampleDominantFeatures
-#' @export
-setMethod("addPerSampleDominantTaxa", signature = c(x = "SummarizedExperiment"),
-        function(x, ...){
-            .Deprecated(old ="addPerSampleDominantTaxa", 
-                        new = "addPerSampleDominantFeatures", 
-                        msg = "The 'addPerSampleDominantTaxa' function is deprecated. Use 'addPerSampleDominantFeatures' instead.")
-            addPerSampleDominantFeatures(x, ...)
-        }
-)
-
-
 ########################## HELP FUNCTIONS summary ##############################
 
 # top entries in a vector or given field in a data frame

R/summaries.R

@@ -228,7 +228,7 @@ setMethod("summarizeDominance", signature = c(x = "SummarizedExperiment"),
                  call. = FALSE)
         }
         # Adds dominant taxa to colData
-        dominant_taxa <- perSampleDominantFeatures(x, ...)
+        dominant_taxa <- getDominant(x, ...)
         data <- colData(x)
         # If the length of dominant taxa is not equal to number of rows, then add rows
         # because there are multiple dominant taxa