bdiv_ord_plot: Ordinate samples and taxa on a 2D plane based on beta...

In cmmr/rbiom: Read/Write, Analyze, and Visualize 'BIOM' Data

Ordinate samples and taxa on a 2D plane based on beta diversity distances.

Description

Ordinate samples and taxa on a 2D plane based on beta diversity distances.

Usage

bdiv_ord_plot(
  biom,
  bdiv = "Bray-Curtis",
  ord = "UMAP",
  weighted = TRUE,
  layers = "petm",
  stat.by = NULL,
  color.by = stat.by,
  shape.by = stat.by,
  facet.by = NULL,
  colors = TRUE,
  shapes = TRUE,
  tree = NULL,
  test = "adonis2",
  seed = 0,
  permutations = 999,
  rank = -1,
  taxa = 4,
  p.top = Inf,
  p.adj = "fdr",
  unc = "singly",
  caption = TRUE,
  ...
)

Arguments

biom	An rbiom object, such as from as_rbiom(). Any value accepted by as_rbiom() can also be given here.
bdiv	Beta diversity distance algorithm(s) to use. Options are: "Bray-Curtis", "Manhattan", "Euclidean", "Jaccard", and "UniFrac". For "UniFrac", a phylogenetic tree must be present in biom or explicitly provided via ⁠tree=⁠. Default: "Bray-Curtis" Multiple/abbreviated values allowed.
ord	Method for reducing dimensionality. Options are: "UMAP" - Uniform manifold approximation and projection; uwot::umap(). "PCoA" - Principal coordinate analysis; ape::pcoa(). "NMDS" - Nonmetric multidimensional scaling; vegan::metaMDS(). "tSNE" - t-distributed stochastic neighbor embedding; tsne::tsne(). Default: "UMAP" Multiple/abbreviated values allowed.
weighted	Take relative abundances into account. When weighted=FALSE, only presence/absence is considered. Default: TRUE Multiple values allowed.
layers	One or more of c("point", "spider", "ellipse", "name", "mean", "taxon", "arrow"). The first four are sample-centric; the last three are taxa-centric. Single letter abbreviations are also accepted. For instance, c("point", "ellipse") is equivalent to c("p", "e") and "pe". See plot types for examples of each. Default: "pe"
stat.by	The categorical or numeric metadata field over which statistics should be calculated. Required.
color.by, shape.by, facet.by, limit.by	Metadata columns to use for aesthetics and partitioning. See below for details. Default: NULL
colors	How to color the groups. Options are: TRUE - Automatically select colorblind-friendly colors. FALSE or NULL - Don't use colors. a palette name - Auto-select colors from this set. E.g. "okabe" character vector - Custom colors to use. E.g. c("red", "#00FF00") named character vector - Explicit mapping. E.g. c(Male = "blue", Female = "red") See "Aesthetics" section below for additional information. Default: TRUE
shapes	Shapes for each group. Options are similar to colors's: TRUE, FALSE, NULL, shape names (typically integers 0 - 17), or a named vector mapping groups to specific shape names. See "Aesthetics" section below for additional information. Default: TRUE
tree	A phylo object representing the phylogenetic relationships of the taxa in biom. Only required when computing UniFrac distances. Default: biom$tree
test	Permutational test for accessing significance. Options are: "adonis2" - Permutational MANOVA; vegan::adonis2(). "mrpp" - Multiple response permutation procedure; vegan::mrpp(). "none" - Don't run any statistics. Default: "adonis2" Abbreviations are allowed.
seed	Random seed for permutations. Default: 0
permutations	Number of random permutations to use. Default: 999
rank	What rank(s) of taxa to display. E.g. "Phylum", "Genus", ".otu", etc. An integer vector can also be given, where 1 is the highest rank, 2 is the second highest, -1 is the lowest rank, -2 is the second lowest, and 0 is the OTU "rank". Run biom$ranks to see all options for a given rbiom object. Default: -1.
taxa	Which taxa to display. An integer value will show the top n most abundant taxa. A value 0 <= n < 1 will show any taxa with that mean abundance or greater (e.g. 0.1 implies >= 10%). A character vector of taxa names will show only those named taxa. Default: 6.
p.top	Only display taxa with the most significant differences in abundance. If p.top is >= 1, then the p.top most significant taxa are displayed. If p.top is less than one, all taxa with an adjusted p-value <= p.top are displayed. Recommended to be used in combination with the taxa parameter to set a lower bound on the mean abundance of considered taxa. Default: Inf
p.adj	Method to use for multiple comparisons adjustment of p-values. Run p.adjust.methods for a list of available options. Default: "fdr"
unc	How to handle unclassified, uncultured, and similarly ambiguous taxa names. Options are: "singly" - Replaces them with the OTU name. "grouped" - Replaces them with a higher rank's name. "drop" - Excludes them from the result. "asis" - To not check/modify any taxa names. Default: "singly" Abbreviations are allowed.
caption	Add methodology caption beneath the plot. Default: TRUE
...	Parameters for layer geoms (e.g. ggplot2::geom_point()). Prefixing parameter names with a layer name ensures that a particular parameter is passed to, and only to, that layer. For instance, point.size = 2 or p.size = 2 ensures only the points have their size set to 2. Points can also be controlled with the pt. prefix.

Value

A ggplot2 plot.
The computed sample coordinates and ggplot command are available as $data and $code respectively.
If color.by is given, then $stats and $stats$code are set.
If rank is given, then $data$taxa_coords, $taxa_stats, and $taxa_stats$code are set.

See Also

Other beta_diversity: bdiv_boxplot(), bdiv_corrplot(), bdiv_heatmap(), bdiv_ord_table(), bdiv_stats(), bdiv_table(), distmat_stats()

Other ordination: bdiv_ord_table(), distmat_ord_table()

Other visualization: adiv_boxplot(), adiv_corrplot(), bdiv_boxplot(), bdiv_corrplot(), bdiv_heatmap(), plot_heatmap(), rare_corrplot(), rare_multiplot(), rare_stacked(), stats_boxplot(), stats_corrplot(), taxa_boxplot(), taxa_corrplot(), taxa_heatmap(), taxa_stacked()

Examples

    library(rbiom)
    
    biom <- rarefy(hmp50)
    
    bdiv_ord_plot(biom, layers="pemt", stat.by="Body Site", rank="g")
    

cmmr/rbiom documentation built on April 28, 2024, 6:38 a.m.