Add reference page and vignettes for pkgdown site (#56)

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: MicrobiomeR
 Title: Analyze Microbiome Data
-Version: 0.1.2
+Version: 0.2.0
 Authors@R: c(
     person("Robert", "Gilmore", email = "[email protected]", role = "cre"),
     person("Shaurita", "Hutchins", email = "[email protected]", role = "aut"))
@@ -48,7 +48,9 @@ Imports:
     forcats,
     ggrepel,
     scales,
-    vegan
+    vegan,
+    leaflet,
+    htmlwidgets
 Suggests:
     knitr,
     testthat,

NAMESPACE

@@ -6,20 +6,20 @@ export(alpha_diversity_plot)
 export(as_MicrobiomeR_format)
 export(as_analyzed_format)
 export(as_basic_format)
+export(as_custom_format)
 export(as_phyloseq_format)
 export(as_raw_format)
 export(combination_palette)
 export(correlation_plot)
 export(cov_filter)
+export(create_phyloseq)
 export(create_pub_table)
-export(format_metacoder_object)
 export(get_alpha_diversity_measures)
 export(get_color_palette)
 export(get_correlation_plots)
 export(get_heat_tree_parameters)
 export(get_heat_tree_plots)
 export(get_output_dir)
-export(get_phyloseq_obj)
 export(is_analyzed_format)
 export(is_basic_format)
 export(is_phyloseq_format)
@@ -34,7 +34,8 @@ export(otu_proportion_filter)
 export(parse_taxonomy_silva_128)
 export(pick_new_outgroup)
 export(root_by_longest_edge)
-export(sample_filter)
+export(root_phyloseq_tree)
+export(sample_id_filter)
 export(save_barplot)
 export(save_correlation_plots)
 export(save_heat_tree_plots)

NEWS.md

@@ -1,3 +1,30 @@
+# MicrobiomeR 0.2.0
+
+## Documentation Updates
+
+* Added vignettes to package and pkgdown config.
+  * About
+  * Introduction
+  * Data Wrangling
+  * Filtering
+  * Analysis
+* Added reference sections to pkgdown config corresponding to @family tag.
+  * Import
+  * Formatting
+  * Validation
+  * Filtering (Basic, Advanced, Other)
+  * Visualization
+  * Color Palettes
+
+## Functional Changes
+
+* Renamed `sample_filter` to `sample_id_filter`.
+* Renamed `get_phyloseq_obj` to `create_phyloseq`.
+* Renamed `format_metacoder_object` to `as_custom_format`.
+* Updated `vlookup` and `get_color_palette` parameters.
+* Added the `root_phyloseq_tree` function.
+* Fixed minor bugs in code and docs.
+
 # MicrobiomeR 0.1.3
 
 * Added custom css for pkgdown.

R/MicrobiomeR-package.R

@@ -0,0 +1,27 @@
+#' MicrobiomeR
+#'
+#' A microbiome workflow package using phyloseq for data import, metacoder for data analysis,
+#' and ggplot2 for data visualization.
+#'
+#' The goal of this package is to enhance the use of the \code{\link[metacoder:metacoder]{metacoder}} package by
+#' providing tools that mimic the \code{\link[phyloseq:phyloseq-package]{phyloseq}} package.  The only difference being that
+#' the main data object is a \code{\link[taxa:taxmap]{taxmap object}} instead of a \code{\link[phyloseq:phyloseq-class]{phyloseq object}}.
+#'
+#' @section Other Documentation:
+#' Below are some links to helpful R package used, while developing this package.
+#'
+#' \describe{
+#'   \item{metacoder}{\url{https://grunwaldlab.github.io/metacoder_documentation/}}
+#'   \item{taxa}{\url{https://github.com/ropensci/taxa}}
+#'   \item{phyloseq}{\url{http://joey711.github.io/phyloseq/}}
+#'   \item{microbiome}{\url{http://microbiome.github.io/microbiome/}}
+#'   \item{MicrobiomeR}{\url{https://github.com/vallenderlab/MicrobiomeR}
+#' }}
+#' The [MicrobiomeR_Workflow] and [MicrobiomeR_Formats] help sections are also useful for understanding the
+#' package.
+#'
+#'
+#' @author Rob Gilmore and Shaurita Hutchins
+#' @name MicrobiomeR
+#' @docType package
+NULL

R/barplot.R

@@ -126,6 +126,7 @@ stacked_barplot <- function(obj, tax_level = "Phylum", fill = "Phylum", xlabel =
 #' }
 #' }
 #' @export
+#' @family Visualizations
 #' @rdname save_barplot
 #' @seealso
 #'

R/correlation-plot.R

@@ -5,6 +5,7 @@
 #' @param secondary_rank The secondary rank used to color the points.  Can be an integer specifying
 #' the number of supertaxon ranks above the primary rank or the name of a supertaxon rank.  Default: TRUE
 #' @param wp_value The Wilcoxian P-Value used to represent significant points.  Default: 0.05
+#' @param pal_func A palette function that returns grDevices::colorRampPalette.
 #' @return A 1:1 correlation plot built with ggplot2.
 #' @pretty_print TRUE
 #' @details Correlation plots help to better explain the heat tree findings.
@@ -36,7 +37,7 @@
 #' @importFrom ggrepel geom_label_repel
 #' @importFrom crayon yellow
 correlation_plot <- function(obj, primary_rank, secondary_rank = TRUE,
-                             wp_value = 0.05) {
+                             wp_value = 0.05, pal_func = NULL) {
   metacoder_object <- object_handler(obj)
   metacoder_object <- validate_MicrobiomeR_format(obj = metacoder_object,
                                                   valid_formats = c("analyzed_format"))
@@ -99,7 +100,17 @@ correlation_plot <- function(obj, primary_rank, secondary_rank = TRUE,
   background_limits <- data.frame(id = c("1", "1", "1", "2", "2", "2"), x = c(0, Inf, 0, 0, Inf, Inf), y = c(0, Inf, Inf, 0, 0, Inf))
   # Get a color palette
   secondary_taxa <- length(unique(primary_data[[(secondary_rank)]]))
-  myPal <- get_color_palette(color_no = secondary_taxa, display = FALSE)
+  if (is.null(pal_func)) {
+    pal_func <- combination_palette(
+      magma = list(palette = viridis::magma, args = list(n=500), range=450:500, rev=TRUE),
+      inferno = list(palette = viridis::inferno, args = list(n=500), range=100:400, rev=TRUE),
+      cividis = list(palette = viridis::cividis, args = list(n=500), range=100:200, rev=TRUE),
+      viridis = list(palette = viridis::viridis, args = list(n=500), range=100:480))
+  }
+  myPal <- get_color_palette(
+    pal_func = pal_func,
+    color_no = secondary_taxa,
+    display = FALSE)
 
   # Start ggplot2 workflow
   corr <- ggplot2::ggplot(primary_data, ggplot2::aes(x = mean_treat1, y = mean_treat2)) +
@@ -115,14 +126,15 @@ correlation_plot <- function(obj, primary_rank, secondary_rank = TRUE,
     ggplot2::scale_fill_manual(values = c("red", "blue", myPal), guide = FALSE) +
     ggplot2::scale_color_manual(values = c(myPal), name = sprintf("%s:", c(secondary_rank)), guide = ggplot2::guide_legend(ncol = 2)) +
     ggplot2::geom_abline(slope = 1, intercept = 0, linetype = "dashed")
+  message(crayon::green(sprintf("Generating Correlation Plot for %s with color based on %s", crayon::bgWhite(primary_rank), crayon::bgWhite(secondary_rank))))
   return(corr)
 }
 
 #' @title Get Multiple Correlation Plots
 #' @description This function allows the user to create a list of multiple correlation plots.
 #' @param obj PARAM_DESCRIPTION
-#' @param primary_rank A vector of primary ranks used to label the points.
-#' @param secondary_rank The secondary rank used to color the points.  Can be an integer specifying
+#' @param primary_ranks A vector of primary ranks used to label the points.
+#' @param secondary_ranks  The secondary rank used to color the points.  Can be an integer specifying
 #' the number of supertaxon ranks above the primary rank or the name of a supertaxon rank.  Default: TRUE
 #' @param pairwise This does a pairwise comparison of the primary and secondary ranks.  Default: FALSE
 #' @param ... An optional list of parameters to use in the correlation_plot function.

R/heat-tree.R

@@ -98,7 +98,7 @@ get_heat_tree_plots <- function(obj, rank_list = NULL, ...) {
 #'
 #'  \code{\link[purrr]{list_modify}}
 #'
-#'  \code{\link[rlang]{enquos}},  \code{\link[rlang]{is_quosure}},  \code{\link[rlang]{eval_tidy}}
+#'  \code{\link[rlang:quotation]{enquos}},  \code{\link[rlang:quosure]{is_quosure}},  \code{\link[rlang]{eval_tidy}}
 #' @importFrom taxa n_obs taxon_names
 #' @importFrom purrr list_modify
 #' @importFrom rlang enquos is_quosure eval_tidy

R/metacoder-formatting.R

@@ -106,8 +106,7 @@ is_raw_format <- function(obj) {
 #'     print(sprintf("It's %s!", fmt))
 #' }
 #'  }
-#'  }
-#' }
+#'}
 #' @export
 #' @family Validation
 #' @rdname is_basic_format
@@ -138,7 +137,6 @@ is_basic_format <- function(obj) {
 #'     print(sprintf("It's %s!", fmt))
 #' }
 #'  }
-#'  }
 #' }
 #' @export
 #' @family Validation
@@ -212,6 +210,51 @@ order_metacoder_data <- function(obj) {
   return(mo_clone)
 }
 
+#' @title Validate MicrobiomeR Format
+#' @description This funciton validates that taxmap/metacoder objects are in a valid format MicrobiomeR format.
+#' @param obj A Taxmap/metacoder object.
+#' @param validated This parameter provides a way to override validation steps.  Use carefully.  Default: FALSE
+#' @param valid_formats A vector of formats that are used for validation.
+#' @param force_format A logical denoting if the selected format is to be forced.  Default: FALSE
+#' @param min_or_max A base function (min or max) that determines which format is to be forced.
+#' This is particularly useful if you provide multiple \emph{valid_formats}.  Min will choose the lowest
+#' level format, while max will choose the highest level format.  Default: base::max
+#' @param ... An optional list of parameters to use in \code{\link[MicrobiomeR]{as_MicrobiomeR_format}}.
+#' @return If the object is validated, a Taxmap/metacoder object.
+#' @details This function can provide a way to check if a taxmap object has undergone a
+#' \code{\link[MicrobiomeR:MicrobiomeR_Workflow]{MicrobiomeR Style Workflow}}.
+#' @export
+#' @family Validation
+#' @rdname validate_MicrobiomeR_format
+#' @seealso
+#'  \code{\link[MicrobiomeR]{which_format}},  \code{\link[MicrobiomeR]{as_MicrobiomeR_format}}
+#' @importFrom glue glue
+#' @importFrom crayon bgWhite green yellow red
+validate_MicrobiomeR_format <- function(obj, validated = FALSE, valid_formats, force_format = FALSE, min_or_max = base::max, ...) {
+  mo_clone <- obj$clone()
+  format_list <- pkg.private$format_level_list
+  if (validated == TRUE) {
+    return(mo_clone)
+  }
+  fmt <- which_format(obj = mo_clone)
+  rank_list <- c(format_list[[fmt]])
+  high_rank <- fmt
+  if (fmt %in% valid_formats) {
+    return(mo_clone)
+  } else if (force_format == TRUE) {
+    for (v_fmt in valid_formats) {
+      rank_list <- c(rank_list, format_list[[v_fmt]])
+      high_rank <- ifelse(format_list[[v_fmt]] >= min_or_max(rank_list), v_fmt, high_rank)
+    }
+    message(crayon::yellow(glue::glue("Forcing the metacoder object from the ", crayon::bgWhite(crayon::red({fmt})), " to the ",
+                                      crayon::bgWhite(crayon::green({high_rank})),".")))
+    mo_clone <- as_MicrobiomeR_format(obj = mo_clone, format = high_rank, ...)
+    return(mo_clone)
+  } else {
+    stop(glue::glue("The metacoder object is not in one of the valid formats: {valid_formats}." ))
+  }
+}
+
 #' @title As Raw MicrobiomeR Format
 #' @description Converts a metacoder object to the raw_format.
 #' @param obj An object to be converted to a metacoder object with \code{\link[MicrobiomeR]{object_handler}}.
@@ -392,7 +435,7 @@ as_analyzed_format <- function(obj, cols = NULL, groups = NULL, combinations = N
 #' @family Formatting
 #' @rdname as_MicrobiomeR_format
 #' @seealso
-#'  \code{\link[MicrobiomeR]{which_format}},  \code{\link[MicrobiomeR]{as_raw_format}},  \code{\link[MicrobiomeR]{as_basic_format}},  \code{\link[MicrobiomeR]{as_analyzed_format}},  \code{\link[MicrobiomeR]{as_phyloseq_format}},  \link[MicrobiomeR]{object_handler}},  \code{\link[MicrobiomeR]{order_metacoder_data}}
+#'  \code{\link[MicrobiomeR]{which_format}},  \code{\link[MicrobiomeR]{as_raw_format}},  \code{\link[MicrobiomeR]{as_basic_format}},  \code{\link[MicrobiomeR]{as_analyzed_format}},  \code{\link[MicrobiomeR]{as_phyloseq_format}},  \code{\link[MicrobiomeR]{object_handler}},  \code{\link[MicrobiomeR]{order_metacoder_data}}
 #' @importFrom glue glue
 #' @importFrom crayon silver green red
 as_MicrobiomeR_format <- function(obj, format, ...) {
@@ -458,7 +501,7 @@ as_phyloseq_format <- function(obj, otu_table="otu_abundance", tax_data="otu_ann
   return(mo_clone)
 }
 
-#' @title Format Metacoder Objects
+#' @title As Custom MicrobiomeR Format
 #' @description A function for formatting metacoder objects in the MicrobiomeR format.  This function
 #' attempts to give more customization than the as_*_format functions.
 #' @param obj An object to be converted to a metacoder object with \code{\link[MicrobiomeR]{object_handler}}.
@@ -471,12 +514,12 @@ as_phyloseq_format <- function(obj, otu_table="otu_abundance", tax_data="otu_ann
 #' @details This function is meant to be more helpful for customizing the metacoder object.
 #' @export
 #' @family Formatting
-#' @rdname format_metacoder_object
+#' @rdname as_custom_format
 #' @seealso
 #'  \code{\link[MicrobiomeR]{object_handler}},  \code{\link[MicrobiomeR]{which_format}},  \code{\link[MicrobiomeR]{order_metacoder_data}},  \code{\link[MicrobiomeR]{as_MicrobiomeR_format}}
 #' @importFrom glue glue
 #' @importFrom crayon red
-format_metacoder_object <- function(obj, format, change_name_list = NULL, ...) {
+as_custom_format <- function(obj, format, change_name_list = NULL, ...) {
 
   # Metacoder Objects
   obj <- object_handler(obj = obj)
@@ -538,48 +581,5 @@ format_metacoder_object <- function(obj, format, change_name_list = NULL, ...) {
   return(mo_clone)
 }
 
-#' @title Validate MicrobiomeR Format
-#' @description This funciton validates that taxmap/metacoder objects are in a valid format MicrobiomeR format.
-#' @param obj A Taxmap/metacoder object.
-#' @param validated This parameter provides a way to override validation steps.  Use carefully.  Default: FALSE
-#' @param valid_formats A vector of formats that are used for validation.
-#' @param force_format A logical denoting if the selected format is to be forced.  Default: FALSE
-#' @param min_or_max A base function (min or max) that determines which format is to be forced.
-#' This is particularly useful if you provide multiple \emph{valid_formats}.  Min will choose the lowest
-#' level format, while max will choose the highest level format.  Default: base::max
-#' @param ... An optional list of parameters to use in \code{\link[MicrobiomeR]{as_MicrobiomeR_format}}.
-#' @return If the object is validated, a Taxmap/metacoder object.
-#' @details This function can provide a way to check if a taxmap object has undergone a
-#' \code{\link[MicrobiomeR:MicrobiomeR_Workflow]{MicrobiomeR Style Workflow}}.
-#' @export
-#' @family Validation
-#' @rdname validate_MicrobiomeR_format
-#' @seealso
-#'  \code{\link[MicrobiomeR]{which_format}},  \code{\link[MicrobiomeR]{as_MicrobiomeR_format}}
-#' @importFrom glue glue
-#' @importFrom crayon bgWhite green yellow red
-validate_MicrobiomeR_format <- function(obj, validated = FALSE, valid_formats, force_format = FALSE, min_or_max = base::max, ...) {
-  mo_clone <- obj$clone()
-  format_list <- pkg.private$format_level_list
-  if (validated == TRUE) {
-    return(mo_clone)
-  }
-  fmt <- which_format(obj = mo_clone)
-  rank_list <- c(format_list[[fmt]])
-  high_rank <- fmt
-  if (fmt %in% valid_formats) {
-    return(mo_clone)
-  } else if (force_format == TRUE) {
-    for (v_fmt in valid_formats) {
-      rank_list <- c(rank_list, format_list[[v_fmt]])
-      high_rank <- ifelse(format_list[[v_fmt]] >= min_or_max(rank_list), v_fmt, high_rank)
-    }
-    message(crayon::yellow(glue::glue("Forcing the metacoder object from the ", crayon::bgWhite(crayon::red({fmt})), " to the ",
-                       crayon::bgWhite(crayon::green({high_rank})),".")))
-    mo_clone <- as_MicrobiomeR_format(obj = mo_clone, format = high_rank, ...)
-    return(mo_clone)
-  } else {
-    stop(glue::glue("The metacoder object is not in one of the valid formats: {valid_formats}." ))
-  }
-}
+