diff --git a/DESCRIPTION b/DESCRIPTION index 3360462fa..a3ea2249f 100644 --- a/DESCRIPTION +++ b/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", diff --git a/NAMESPACE b/NAMESPACE index 83eae735d..7ce95c6c6 100644 --- a/NAMESPACE +++ b/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) diff --git a/NEWS b/NEWS index 76ea5f1e4..221c0e9f7 100644 --- a/NEWS +++ b/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 diff --git a/R/deprecate.R b/R/deprecate.R index 35a295b2d..39277f0aa 100644 --- a/R/deprecate.R +++ b/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, ...) + } +) diff --git a/R/dominantTaxa.R b/R/getDominant.R similarity index 73% rename from R/dominantTaxa.R rename to R/getDominant.R index 7134d2203..ab757bca0 100644 --- a/R/dominantTaxa.R +++ b/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,10 +30,10 @@ #' 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. #' @@ -41,22 +41,22 @@ #' \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 diff --git a/R/summaries.R b/R/summaries.R index 0f051c4df..99e95531b 100644 --- a/R/summaries.R +++ b/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 diff --git a/man/deprecate.Rd b/man/deprecate.Rd index 39003845a..0518a4b51 100644 --- a/man/deprecate.Rd +++ b/man/deprecate.Rd @@ -97,6 +97,14 @@ \alias{getPrevalentTaxa,SummarizedExperiment-method} \alias{subsampleCounts} \alias{subsampleCounts,SummarizedExperiment-method} +\alias{addPerSampleDominantFeatures} +\alias{addPerSampleDominantFeatures,SummarizedExperiment-method} +\alias{addPerSampleDominantTaxa} +\alias{addPerSampleDominantTaxa,SummarizedExperiment-method} +\alias{perSampleDominantFeatures} +\alias{perSampleDominantFeatures,SummarizedExperiment-method} +\alias{perSampleDominantTaxa} +\alias{perSampleDominantTaxa,SummarizedExperiment-method} \title{These functions will be deprecated. Please use other functions instead.} \usage{ cluster(x, ...) @@ -288,6 +296,22 @@ getPrevalentTaxa(x, ...) subsampleCounts(x, ...) \S4method{subsampleCounts}{SummarizedExperiment}(x, ...) + +addPerSampleDominantFeatures(x, ...) + +\S4method{addPerSampleDominantFeatures}{SummarizedExperiment}(x, ...) + +addPerSampleDominantTaxa(x, ...) + +\S4method{addPerSampleDominantTaxa}{SummarizedExperiment}(x, ...) + +perSampleDominantFeatures(x, ...) + +\S4method{perSampleDominantFeatures}{SummarizedExperiment}(x, ...) + +perSampleDominantTaxa(x, ...) + +\S4method{perSampleDominantTaxa}{SummarizedExperiment}(x, ...) } \arguments{ \item{x}{A diff --git a/man/perSampleDominantTaxa.Rd b/man/getDominant.Rd similarity index 65% rename from man/perSampleDominantTaxa.Rd rename to man/getDominant.Rd index 935e60510..ea3697050 100644 --- a/man/perSampleDominantTaxa.Rd +++ b/man/getDominant.Rd @@ -1,17 +1,13 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/dominantTaxa.R -\name{perSampleDominantTaxa} -\alias{perSampleDominantTaxa} -\alias{perSampleDominantFeatures} -\alias{perSampleDominantFeatures,SummarizedExperiment-method} -\alias{perSampleDominantTaxa,SummarizedExperiment-method} -\alias{addPerSampleDominantFeatures} -\alias{addPerSampleDominantTaxa} -\alias{addPerSampleDominantFeatures,SummarizedExperiment-method} -\alias{addPerSampleDominantTaxa,SummarizedExperiment-method} +% Please edit documentation in R/getDominant.R +\name{getDominant} +\alias{getDominant} +\alias{getDominant,SummarizedExperiment-method} +\alias{addDominant} +\alias{addDominant,SummarizedExperiment-method} \title{Get dominant taxa} \usage{ -perSampleDominantFeatures( +getDominant( x, assay.type = assay_name, assay_name = "counts", @@ -22,7 +18,7 @@ perSampleDominantFeatures( ... ) -\S4method{perSampleDominantFeatures}{SummarizedExperiment}( +\S4method{getDominant}{SummarizedExperiment}( x, assay.type = assay_name, assay_name = "counts", @@ -33,19 +29,9 @@ perSampleDominantFeatures( ... ) -perSampleDominantTaxa(x, ...) +addDominant(x, name = "dominant_taxa", other.name = "Other", n = NULL, ...) -\S4method{perSampleDominantTaxa}{SummarizedExperiment}(x, ...) - -addPerSampleDominantFeatures( - x, - name = "dominant_taxa", - other.name = "Other", - n = NULL, - ... -) - -\S4method{addPerSampleDominantFeatures}{SummarizedExperiment}( +\S4method{addDominant}{SummarizedExperiment}( x, name = "dominant_taxa", other.name = "Other", @@ -53,10 +39,6 @@ addPerSampleDominantFeatures( complete = FALSE, ... ) - -addPerSampleDominantTaxa(x, ...) - -\S4method{addPerSampleDominantTaxa}{SummarizedExperiment}(x, ...) } \arguments{ \item{x}{A @@ -82,10 +64,10 @@ dominant features in the data. Default is "Other".} Default is NULL, which defaults that each sample is assigned a dominant taxon.} \item{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.} @@ -93,11 +75,11 @@ list that includes all dominant taxa for each sample into colData.} \code{rank} is specified.} \item{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}.} } \value{ -\code{perSampleDominantFeatures} returns a named character vector \code{x} -while \code{addPerSampleDominantFeatures} returns +\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*}. } @@ -107,10 +89,10 @@ These functions return information about the most dominant taxa in a object. } \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 @@ -122,10 +104,10 @@ data(GlobalPatterns) 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) } \author{ diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 8dd18ecb5..41d2f78d0 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -51,7 +51,7 @@ reference: - hierarchy-tree - subtitle: Dominance - contents: - - perSampleDominantTaxa + - getDominant - estimateDominance - subtitle: Evenness indeces - contents: diff --git a/tests/testthat/test-5dominantTaxa.R b/tests/testthat/test-5dominantTaxa.R index 40276aea0..a39d236c5 100644 --- a/tests/testthat/test-5dominantTaxa.R +++ b/tests/testthat/test-5dominantTaxa.R @@ -1,8 +1,8 @@ -context("perSampleDominantFeatures") +context("getDominant") -test_that("perSampleDominantFeatures", { +test_that("getDominant", { - test_perSampleDominantFeatures <- function(tse){ + test_getDominant <- function(tse){ # names exp.names.one <- c("CL3", "CC1", "SV1", "M31Fcsw", @@ -18,10 +18,10 @@ test_that("perSampleDominantFeatures", { "549656","549656","549656") names(exp.vals.one) <- exp.names.one - expect_equal(perSampleDominantFeatures(tse)[1:15], exp.vals.one) + expect_equal(getDominant(tse)[1:15], exp.vals.one) # Test at taxonomic level for values are passed to agglomerateRanks - perSampleDominantFeatures(tse, rank = "Genus", na.rm = FALSE) + getDominant(tse, rank = "Genus", na.rm = FALSE) exp.vals.two <- c("Genus:CandidatusSolibacter", "Genus:MC18", "Class:Chloracidobacteria", "Genus:Bacteroides", @@ -31,19 +31,19 @@ test_that("perSampleDominantFeatures", { "Genus:Dolichospermum", "Family:ACK-M1", "Order:Stramenopiles","Order:Stramenopiles","Order:Stramenopiles") names(exp.vals.two) <- exp.names.one - expect_equal(perSampleDominantFeatures(tse, + expect_equal(getDominant(tse, rank = "Genus", na.rm = FALSE)[1:15], exp.vals.two) # Check if DominantTaxa is added to coldata - expect_equal(colData(addPerSampleDominantFeatures(tse, - name="dominant"))$dominant[1:15], + expect_equal(colData(addDominant(tse, + name="dominant"))$dominant[1:15], exp.vals.one) - expect_equal(colData(addPerSampleDominantFeatures(tse, - rank = "Genus", - na.rm = FALSE, - name="dominant"))$dominant[1:15], + expect_equal(colData(addDominant(tse, + rank = "Genus", + na.rm = FALSE, + name="dominant"))$dominant[1:15], exp.vals.two) tse1 <- tse @@ -51,32 +51,32 @@ test_that("perSampleDominantFeatures", { assay(tse1)[1, 1] <- max(assay(tse1)[, 1]) # Get dominant taxa - dominant_taxa <- perSampleDominantFeatures(tse, complete = TRUE) - dominant_taxa1 <- perSampleDominantFeatures(tse1, complete = TRUE) + dominant_taxa <- getDominant(tse, complete = TRUE) + dominant_taxa1 <- getDominant(tse1, complete = TRUE) # dominant_taxa1 should have one additional element expect_equal( length(unlist(dominant_taxa1)), length(dominant_taxa)+1) # Add dominant taxa to colData and check that it equals to dominant taxa - # that is got by perSampleDominantFeatures - add_dom <- unlist(colData(addPerSampleDominantFeatures(tse, complete = FALSE))$dominant_taxa) - dominant_taxa <- perSampleDominantFeatures(tse, complete = FALSE) + # that is got by getDominant + add_dom <- unlist(colData(addDominant(tse, complete = FALSE))$dominant_taxa) + dominant_taxa <- getDominant(tse, complete = FALSE) expect_equal(unname(add_dom), unname(dominant_taxa)) # Test alias - alias <- unlist(colData(addPerSampleDominantFeatures(tse))$dominant_taxa) + alias <- unlist(colData(addDominant(tse))$dominant_taxa) expect_equal(unname(add_dom), unname(alias)) - alias <- perSampleDominantFeatures(tse) + alias <- getDominant(tse) expect_equal(alias, dominant_taxa) # Test that chosen dominant taxon is included in the list of dominant taxa for those samples with multiple dominant taxa - expect_warning(add_dom <- unlist(colData(addPerSampleDominantFeatures(tse1, complete = FALSE))$dominant_taxa)) + expect_warning(add_dom <- unlist(colData(addDominant(tse1, complete = FALSE))$dominant_taxa)) expect_true(add_dom[[1]] %in% dominant_taxa1) } # TSE object data(GlobalPatterns, package="mia") - test_perSampleDominantFeatures(GlobalPatterns) + test_getDominant(GlobalPatterns) test_that("summarizeDominance", {