create new generic converter

NAMESPACE

@@ -29,6 +29,10 @@ export(calculateOverlap)
 export(calculateRDA)
 export(calculateUnifrac)
 export(cluster)
+export(convertFromBIOM)
+export(convertFromDADA2)
+export(convertFromPhyloseq)
+export(convertToPhyloseq)
 export(countDominantFeatures)
 export(countDominantTaxa)
 export(estimateDivergence)
@@ -158,6 +162,7 @@ exportMethods(calculateOverlap)
 exportMethods(calculateUnifrac)
 exportMethods(checkTaxonomy)
 exportMethods(cluster)
+exportMethods(convertToPhyloseq)
 exportMethods(countDominantFeatures)
 exportMethods(countDominantTaxa)
 exportMethods(estimateDivergence)

NEWS

@@ -135,7 +135,10 @@ Changes in version 1.13.x
   includes the newly added subsampled assay.
 + Fix bug in mergeFeaturesByPrevalence
 + new aliases calculateDPCoA to getDPCoA, calculateNMDS to getNMDS, calculateRDA to getRDA, 
-calculateCCA to getCCA
+  calculateCCA to getCCA
++ add informative error message in rarefyAssay on assays with strictly-negative values 
 + add informative error message in rarefyAssay on assays with strictly-negative values 
 + Use rbiom package in unifrac implementation
 + Updated parameter names to follow naming convention "parameter.name"
++ rename makeTreeSEFrom* and makePhyloseqFromTreeSE functions and combine their
+  documentation under new manual page convert

R/makeTreeSummarizedExperimentFromBiom.R → R/convertFromBIOM.R

@@ -1,10 +1,16 @@
-#' Loading a biom file
+#' Converters
 #'
-#' For convenience a few functions are available to convert data from a
-#' \sQuote{biom} file or object into a
+#' For convenience a few functions are available to convert BIOM, DADA2 and 
+#' phyloseq objects to 
 #' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}}
+#' objects and 
+#' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}}
+#' objects to phyloseq objects.
 #'
-#' @param file biom file location
+#' @param file BIOM file location
+#' 
+#' @param obj BIOM object to be converted to a 
+#' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}}
 #' 
 #' @param prefix.rm \code{TRUE} or \code{FALSE}: Should
 #' taxonomic prefixes be removed? The prefixes is removed only from detected
@@ -27,22 +33,31 @@
 #' 
 #' @param ... additional arguments 
 #'   \itemize{
-#'        \item \code{patter}: \code{character} value specifying artifacts
+#'        \item{\code{pattern}}{\code{character} value specifying artifacts
 #'        to be removed. If \code{patterns = "auto"}, special characters
-#'        are removed. (default: \code{pattern = "auto"})
+#'        are removed. (default: \code{pattern = "auto"}) 
+#'        } 
 #'    }
 #' 
-#' @return An object of class
+#' @details 
+#' \code{convertFromBIOM} coerces a BIOM object to a 
+#' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}}
+#' object.
+#' 
+#' \code{importBIOM} loads a BIOM file and creates a 
+#' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}} 
+#' object from the BIOM object contained in the loaded file
+#' @return 
+#' \code{importBIOM} returns an object of class
+#'   \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}}
+#'   
+#' \code{convertFromBIOM} returns an object of class
 #'   \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}}
 #'
-#' @name makeTreeSEFromBiom
-#' @seealso
-#' \code{\link[=makeTreeSEFromPhyloseq]{makeTreeSEFromPhyloseq}}
-#' \code{\link[=makeTreeSEFromDADA2]{makeTreeSEFromDADA2}}
-#' \code{\link[=importQIIME2]{importQIIME2}}
-#' \code{\link[=importMothur]{importMothur}}
+#' @name convert
 #'
 #' @examples
+#' ### Load and convert BIOM results to a TreeSE
 #' # Load biom file
 #' library(biomformat)
 #' biom_file <- system.file("extdata", "rich_dense_otu_table.biom",
@@ -53,7 +68,7 @@
 #' 
 #' # Make TreeSE from biom object
 #' biom_object <- biomformat::read_biom(biom_file)
-#' tse <- makeTreeSEFromBiom(biom_object)
+#' tse <- convertFromBIOM(biom_object)
 #' 
 #' # Get taxonomyRanks from prefixes and remove prefixes
 #' tse <- importBIOM(biom_file,
@@ -69,31 +84,30 @@
 #'                     artifact.rm = TRUE)
 NULL
 
-#' @rdname makeTreeSEFromBiom
-#'
+#' \code{importBIOM} loads a BIOM file and creates a TreeSE from the BIOM object
+#' contained in the loaded file.
+#' @rdname convert
 #' @export
 importBIOM <- function(file, ...) {
     .require_package("biomformat")
     biom <- biomformat::read_biom(file)
-    makeTreeSEFromBiom(biom, ...)
+    convertFromBIOM(biom,...)
 }
 
-#' @rdname makeTreeSEFromBiom
-#'
-#' @param x object of type \code{\link[biomformat:read_biom]{biom}}
-#'
-#' @export
+#' \code{convertFromBIOM} creates a TreeSE object from a BIOM object.
 #' @importFrom S4Vectors make_zero_col_DFrame DataFrame
 #' @importFrom dplyr %>% bind_rows
-makeTreeSEFromBiom <- function(
-        x, prefix.rm = removeTaxaPrefixes, 
+#' @rdname convert
+#' @export
+convertFromBIOM <- function(
+        obj, prefix.rm = removeTaxaPrefixes, 
         removeTaxaPrefixes = FALSE, rank.from.prefix = rankFromPrefix, 
         rankFromPrefix = FALSE,
         artifact.rm = remove.artifacts, remove.artifacts = FALSE, ...){
     # input check
     .require_package("biomformat")
-    if(!is(x,"biom")){
-        stop("'x' must be a 'biom' object", call. = FALSE)
+    if(!is(obj,"biom")){
+        stop("'obj' must be a 'biom' object", call. = FALSE)
     }
     if( !.is_a_bool(prefix.rm) ){
         stop("'prefix.rm' must be TRUE or FALSE.", call. = FALSE)
@@ -105,9 +119,9 @@ makeTreeSEFromBiom <- function(
         stop("'artifact.rm' must be TRUE or FALSE.", call. = FALSE)
     }
     #
-    counts <- as(biomformat::biom_data(x), "matrix")
-    sample_data <- biomformat::sample_metadata(x)
-    feature_data <- biomformat::observation_metadata(x)
+    counts <- as(biomformat::biom_data(obj), "matrix")
+    sample_data <- biomformat::sample_metadata(obj)
+    feature_data <- biomformat::observation_metadata(obj)
 
     # colData is initialized with empty tables with rownames if it is NULL
     if( is.null(sample_data) ){
@@ -185,8 +199,8 @@ makeTreeSEFromBiom <- function(
     }
 
     # Adjust row and colnames
-    rownames(counts) <- rownames(feature_data) <- biomformat::rownames(x)
-    colnames(counts) <- rownames(sample_data) <- biomformat::colnames(x)
+    rownames(counts) <- rownames(feature_data) <- biomformat::rownames(obj)
+    colnames(counts) <- rownames(sample_data) <- biomformat::colnames(obj)
 
     # Convert into DataFrame
     sample_data <- DataFrame(sample_data)
@@ -202,14 +216,6 @@ makeTreeSEFromBiom <- function(
     return(tse)
 }
 
-####################### makeTreeSummarizedExperimentFromBiom ###################
-#' @param x object of type \code{\link[biomformat:read_biom]{biom}}
-#' @rdname makeTreeSEFromBiom
-#' @export
-makeTreeSummarizedExperimentFromBiom <- function(x, ...){
-    makeTreeSEFromBiom(x, ...)
-}
-
 ################################ HELP FUNCTIONS ################################
 # This function removes prefixes from taxonomy names
 .remove_prefixes_from_taxa <- function(

R/makeTreeSummarizedExperimentFromDADA2.R → R/convertFromDADA2.R

@@ -1,44 +1,41 @@
 #' Coerce \sQuote{DADA2} results to \code{TreeSummarizedExperiment}
 #'
-#' \code{makeTreeSEFromDADA2} is a wrapper for the
-#' \code{mergePairs} function from the \code{dada2} package.
-#'
-#' @param ... See \code{mergePairs} function for
-#'   more details.
+#' @param ... Addional arguments. For \code{convertFromDADA2}, see 
+#' \code{mergePairs} function for more details.
 #'
 #' @details
-#' A count matrix is constructed via \code{makeSequenceTable(mergePairs(...))}
-#' and rownames are dynamically created as \code{ASV(N)} with \code{N} from
-#' 1 to \code{nrow} of the count tables. The colnames and rownames from the
-#' output of \code{makeSequenceTable} are stored as \code{colnames} and in the
-#' \code{referenceSeq} slot of the \code{TreeSummarizedExperiment},
-#' respectively.
+#' \code{convertFromDADA2} is a wrapper for the
+#' \code{mergePairs} function from the \code{dada2} package.
+#' A count matrix is constructed via 
+#' \code{makeSequenceTable(mergePairs(...))} and rownames are dynamically 
+#' created as \code{ASV(N)} with \code{N} from 1 to \code{nrow} of the count 
+#' tables. The colnames and rownames from the output of \code{makeSequenceTable}
+#' are stored as \code{colnames} and in the \code{referenceSeq} slot of the 
+#' \code{TreeSummarizedExperiment},respectively.
 #'
-#' @return An object of class \code{TreeSummarizedExperiment}
+#' @return \code{convertFromDADA2} returns an object of class 
+#' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}}
 #'
 #' @importFrom S4Vectors SimpleList
 #' @importFrom Biostrings DNAStringSet
 #'
-#' @name makeTreeSEFromDADA2
-#' @seealso
-#' \code{\link[=makeTreeSEFromPhyloseq]{makeTreeSEFromPhyloseq}}
-#' \code{\link[=makeTreeSEFromBiom]{makeTreeSEFromBiom}}
-#' \code{\link[=importQIIME2]{importQIIME2}}
-#' \code{\link[=importMothur]{importMothur}}
+#' @rdname convert
 #'
 #' @export
 #'
 #' @examples
+#' 
+#' ### Coerce DADA2 results to a TreeSE object
 #' if(requireNamespace("dada2")) {
 #'   fnF <- system.file("extdata", "sam1F.fastq.gz", package="dada2")
 #'   fnR = system.file("extdata", "sam1R.fastq.gz", package="dada2")
 #'   dadaF <- dada2::dada(fnF, selfConsist=TRUE)
 #'   dadaR <- dada2::dada(fnR, selfConsist=TRUE)
 #'
-#'   tse <- makeTreeSEFromDADA2(dadaF, fnF, dadaR, fnR)
+#'   tse <- convertFromDADA2(dadaF, fnF, dadaR, fnR)
 #'   tse
 #' }
-makeTreeSEFromDADA2 <- function(...) {
+convertFromDADA2 <- function(...) {
     # input checks
     .require_package("dada2")
     .require_package("stringr")
@@ -62,12 +59,3 @@ makeTreeSEFromDADA2 <- function(...) {
     rownames(output) <- rName
     output
 }
-
-#################### makeTreeSummarizedExperimentFromDADA2 #####################
-#' @param ... See \code{mergePairs} function for
-#'   more details.
-#' @name makeTreeSEFromDADA2
-#' @export
-makeTreeSummarizedExperimentFromDADA2 <- function(...) {
-    makeTreeSEFromDADA2(...)
-}

R/convertFromPhyloseq.R

@@ -0,0 +1,77 @@
+#' @param phy a \code{phyloseq} object
+#' 
+#' @details 
+#' \code{convertFromPhyloseq} converts \code{phyloseq}
+#' objects into 
+#' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}} objects.
+#' All data stored in a \code{phyloseq} object is transferred.
+#'
+#' @return 
+#' \code{convertFromPhyloseq} returns an object of class 
+#' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}}
+#'
+#' @importFrom S4Vectors SimpleList DataFrame make_zero_col_DFrame
+#' @importFrom SummarizedExperiment colData colData<-
+#'
+#' @export
+#'
+#' @rdname convert
+#' @seealso
+#' \code{\link[=importQIIME2]{importQIIME2}}
+#' \code{\link[=importMothur]{importMothur}}
+#'
+#' @examples
+#' 
+#' ### Coerce a phyloseq object to a TreeSE object
+#' if (requireNamespace("phyloseq")) {
+#'     data(GlobalPatterns, package="phyloseq")
+#'     convertFromPhyloseq(GlobalPatterns)
+#'     data(enterotype, package="phyloseq")
+#'     convertFromPhyloseq(enterotype)
+#'     data(esophagus, package="phyloseq")
+#'     convertFromPhyloseq(esophagus)
+#' }
+convertFromPhyloseq <- function(phy, ...) {
+    # input check
+    .require_package("phyloseq")
+    if(!is(phy,"phyloseq")){
+        stop("'phy' must be a 'phyloseq' object")
+    }
+    #
+    # Get the assay
+    counts <- phy@otu_table@.Data
+    # Check the orientation, and transpose if necessary
+    if( !phy@otu_table@taxa_are_rows ){
+        counts <- t(counts)
+    }
+    # Create a list of assays
+    assays <- SimpleList(counts = counts)
+
+    if(!is.null(phy@tax_table@.Data)){
+        rowData <- DataFrame(data.frame(phy@tax_table@.Data))
+    } else{
+        rowData <- S4Vectors::make_zero_col_DFrame(nrow(assays$counts))
+        rownames(rowData) <- rownames(assays$counts)
+    }
+    if(!is.null(phy@sam_data)){
+        colData <- DataFrame(data.frame(phy@sam_data))
+    } else{
+        colData <- S4Vectors::make_zero_col_DFrame(ncol(assays$counts))
+        rownames(colData) <- colnames(assays$counts)
+    }
+    if(!is.null(phy@phy_tree)){
+        rowTree <- phy@phy_tree
+    } else {
+        rowTree <- NULL
+    }
+    if (!is.null(phy@refseq)) {
+        referenceSeq <- phy@refseq
+    } else {
+        referenceSeq <- NULL
+    }
+    TreeSummarizedExperiment(assays = assays,
+                            rowData = rowData,
+                            colData = colData,
+                            rowTree = rowTree,
+                            referenceSeq = referenceSeq)
+}