Add tree and metadata options to importers

R/convertFromBIOM.R

@@ -68,6 +68,13 @@ NULL
 #'
 #' @param file BIOM file location
 #'
+#' @param col.data a DataFrame-like object that includes sample names in
+#'   rownames, or a single \code{character} value defining the file
+#'   path of the sample metadata file (tsv). (Default: \code{NULL}).
+#'
+#' @param tree.file \code{Character scalar}. Optional path to a phylogenetic
+#'   tree. If provided, replaces any tree stored in the BIOM metadata.
+#'
 #' @param ... additional arguments to be passed to \code{convertFromBIOM}
 #'
 #' @details
@@ -110,11 +117,45 @@ NULL
 #' # Clean artifacts from taxonomic data
 #' tse <- importBIOM(biom_file, artifact.rm = TRUE)
 #'
+#' @importFrom ape read.tree
 #' @export
-importBIOM <- function(file, ...) {
+importBIOM <- function(file, col.data = NULL, tree.file = NULL, ...) {
     .require_package("biomformat")
     biom <- biomformat::read_biom(file)
-    convertFromBIOM(biom, ...)
+    tse <- convertFromBIOM(biom, ...)
+
+    # Load sample metadata if provided (overrides BIOM sample metadata)
+    if (!is.null(col.data)) {
+        tse <- .add_coldata(tse, col.data)
+    }
+
+    # Load/replace tree if provided
+    if (!is.null(tree.file)) {
+        if (!.is_non_empty_string(tree.file)) {
+            stop("'tree.file' must be a single character value or NULL.",
+                 call. = FALSE)
+        }
+        tree <- read.tree(tree.file)
+        # Validate that rownames(tse) can be matched to tree tip labels. If
+        # not, give a clear error so users know to construct the TreeSE
+        # without the tree and then add it manually using `changeTree`.
+        if (!all(rownames(tse) %in% tree$tip.label)) {
+            stop(
+                paste(
+                    "Rownames do not match with tree labels. Construct",
+                    "TreeSE without tree (tree.file=NULL) and then add",
+                    "the tree manually with",
+                    "changeTree(tse, tree = tree_object,",
+                    "rowNodeLab = link_vector)",
+                    sep = "\n"
+                ),
+                call. = FALSE
+            )
+        }
+        rowTree(tse) <- tree
+    }
+
+    return(tse)
 }
 
 #' @rdname importBIOM

R/importHumann.R

@@ -8,6 +8,9 @@
 #' path of the sample metadata file. The file must be in \code{tsv} format
 #' (Default: \code{NULL}).
 #' 
+#' @param tree.file \code{Character scalar}. Optional path to a
+#' phylogenetic tree. If provided, the tree is attached as \code{rowTree}.
+#' 
 #' @param colData Deprecated. Use \code{col.data} instead.
 #' 
 #' @param ... additional arguments:
@@ -69,7 +72,8 @@
 #' 
 NULL
 
-importHUMAnN <- function(file, col.data = colData, colData = NULL, ...){
+importHUMAnN <- function(file, col.data = colData, colData = NULL,
+                        tree.file = NULL, ...){
     ################################ Input check ###############################
     if(!.is_non_empty_string(file)){
         stop("'file' must be a single character value.",
@@ -84,6 +88,10 @@ importHUMAnN <- function(file, col.data = colData, colData = NULL, ...){
         stop("'col.data' must be a single character value, DataFrame or NULL.",
             call. = FALSE)
     }
+    if (!is.null(tree.file) && !.is_non_empty_string(tree.file)) {
+        stop("'tree.file' must be a single character value or NULL.",
+             call. = FALSE)
+    }
     ############################## Input check end #############################
     # Humann files has these columns that goes to rowData
     rowdata_col <- c("Pathway", "Gene_Family")
@@ -95,6 +103,11 @@ importHUMAnN <- function(file, col.data = colData, colData = NULL, ...){
     if( !is.null(col.data) ){
         tse <- .add_coldata(tse, col.data)
     }
+    # Add tree if provided
+    if (!is.null(tree.file)) {
+        tree <- ape::read.tree(tree.file)
+        rowTree(tse) <- tree
+    }
     return(tse)
 }
 

R/importMothur.R

@@ -22,6 +22,10 @@
 #' 
 #' @param designFile Deprecated. Use \code{col.file} instead.
 #'
+#' @param tree.file \code{Character scalar}. Optional path to a phylogenetic
+#'   tree in Newick format. If provided, the tree is attached as
+#'   \code{rowTree}.
+#'
 #' @details
 #' Results exported from Mothur can be imported as a
 #' \code{SummarizedExperiment} using \code{importMothur}. Except for the
@@ -72,7 +76,8 @@ importMothur <- function(assay.file = sharedFile,
                         taxonomyFile = NULL,
                         row.file = taxonomyFile,
                         designFile = NULL,
-                        col.file = designFile) {
+                        col.file = designFile,
+                        tree.file = NULL) {
 
     # input check
     if(!.is_non_empty_string(assay.file)){
@@ -87,6 +92,10 @@ importMothur <- function(assay.file = sharedFile,
         stop("'col.file' must be a single character value or NULL.",
             call. = FALSE)
     }
+    if (!is.null(tree.file) && !.is_non_empty_string(tree.file)) {
+        stop("'tree.file' must be a single character value or NULL.",
+             call. = FALSE)
+    }
 
     # Reads the assay.file 
     feature_tab_and_data_to_colData <- .read_mothur_feature(assay.file)
@@ -113,10 +122,17 @@ importMothur <- function(assay.file = sharedFile,
         rownames(sample_meta) <- colnames(feature_tab)
     }
 
-    TreeSummarizedExperiment(
+    tse <- TreeSummarizedExperiment(
         assays = S4Vectors::SimpleList(counts = feature_tab),
         rowData = taxa_tab,
         colData = sample_meta)
+
+    if (!is.null(tree.file)) {
+        tree <- ape::read.tree(tree.file)
+        rowTree(tse) <- tree
+    }
+
+    tse
 }
 
 # These extra information must be added to colData. Return list of assay and