vis_ordinate: Visually appealing ordination plots

In TYMichaelsen/mmtravis: Tools for analysing (meta)transcriptomics data

Description

Ordination plot

Usage

vis_ordinate(data, type = "", transform = "", distmeasure = "", constrain = "")

Arguments

obj	(required) A data object of class 'ampvis2' (see amp_load) or class 'mmt' (see mt_load).
type	(required) Type of ordination method. One of: "PCA": (default) Principal Components Analysis "RDA": Redundancy Analysis (considered the constrained version of PCA) "CA": Correspondence Analysis "CCA": Canonical Correspondence Analysis (considered the constrained version of CA) "DCA": Detrended Correspondence Analysis "NMDS": non-metric Multidimensional Scaling "PCOA" or "MMDS": metric Multidimensional Scaling a.k.a Principal Coordinates Analysis (not to be confused with PCA) Note that PCoA is not performed by the vegan package, but the pcoa function from the APE package.
distmeasure	(required for nMDS and PCoA) Distance measure used for the distance-based ordination methods (nMDS and PCoA). Choose one of the following: "wunifrac": (ampvis2 only) Weighted generalized UniFrac distances (alpha=0.5), calculated by GUniFrac. OBS! Requires a phylogenetic tree. "unifrac": (ampvis2 only) Unweighted UniFrac distances, calculated by GUniFrac. OBS! Requires a phylogenetic tree. "jsd": Jensen-Shannon Divergence, based on http://enterotype.embl.de/enterotypes.html. Any of the distance measures supported by vegdist: "manhattan", "euclidean", "canberra", "bray", "kulczynski", "jaccard", "gower", "altGower", "morisita", "horn", "mountford", "raup", "binomial", "chao", "cao", "mahalanobis". or "none". (default) You can also write your own math formula, see details in vegdist.
transform	(recommended) Transforms the abundances before ordination, choose one of the following: "total", "max", "freq", "normalize", "range", "standardize", "pa" (presence/absense), "chi.square", "hellinger", "log", or "sqrt", see details in decostand. Using the hellinger transformation is a good choice when performing PCA/RDA as it will produce a more ecologically meaningful result (read about the double-zero problem in Numerical Ecology). When the Hellinger transformation is used with CA/CCA it will help reducing the impact of low abundant species. When performing nMDS or PCoA (aka mMDS) it is not recommended to also use data transformation as this will obscure the chosen distance measure. (default: "hellinger")
filter_vars	Remove low signal variables across all samples below this threshold in percent. Setting this to 0 may drastically increase computation time. (default: 0.1)
constrain	(required for RDA and CCA) Variable(s) in the metadata for constrained analyses (RDA and CCA). Multiple variables can be provided by a vector, fx c("Year", "Temperature"), but keep in mind that the more variables selected the more the result will be similar to unconstrained analysis.
x_axis	Which axis from the ordination results to plot as the first axis. Have a look at the $screeplot with detailed_output = TRUE to validate axes. (default: 1)
y_axis	Which axis from the ordination results to plot as the second axis. Have a look at the $screeplot with detailed_output = TRUE to validate axes. (default: 2)
sample_color_by	Color sample points by a variable in the metadata.
sample_color_order	Order the colors in sample_color_by by the order in a vector.
sample_shape_by	Shape sample points by a variable in the metadata.
sample_colorframe	Frame the sample points with a polygon by a variable in the metadata split by the variable defined by sample_color_by, or simply TRUE to frame the points colored by sample_color_by. (default: FALSE)
sample_colorframe_label	Label by a variable in the metadata.
sample_label_by	Label sample points by a variable in the metadata.
sample_label_size	Sample labels text size. (default: 4)
sample_label_segment_color	Sample labels repel-segment color. (default: "black")
sample_point_size	Size of the sample points. (default: 2)
sample_trajectory	Make a trajectory between sample points by a variable in the metadata.
sample_trajectory_group	Make a trajectory between sample points by the sample_trajectory argument, but within individual groups.
sample_plotly	Enable interactive sample points so that they can be hovered to show additional information from the metadata. Provide a vector of the metadata variables to show, or "all" to display all. Click or double click the elements in the legend to hide/show parts of the data. To hide the legend use plotly::layout(amp_ordinate(...), showlegend = FALSE), see more options at https://plot.ly/r/.
var_plot	(logical) Plot variable points or not. (default: FALSE)
var_nlabels	Number of the most extreme variables labels to plot (ordered by the sum of the numerical values of the x,y coordinates. Only makes sense with PCA/RDA).
var_label_by	Label variable points by taxonomy (ampvis2) or variable in genedata (mmt).
var_label_size	Size of the variables text labels. (default: 3)
var_label_color	Color of the variables text labels. (default: "grey10")
var_rescale	(logical) Rescale variables points or not. Basically they will be multiplied by 0.8, for visual convenience only. (default: FALSE)
var_point_size	Size of the variables points. (default: 2)
var_shape	The shape of the variables points, fx 1 for hollow circles or 20 for dots. (default: 20)
var_plotly	(logical) Enable interactive variables points so that they can be hovered to show complete information. (default: FALSE)
envfit_factor	A vector of categorical environmental variables from the metadata to fit onto the ordination plot. See details in envfit.
envfit_numeric	A vector of numerical environmental variables from the metadata to fit arrows onto the ordination plot. The lengths of the arrows are scaled by significance. See details in envfit.
envfit_signif_level	The significance threshold for displaying the results of envfit_factor or envfit_numeric. (default: 0.005)
envfit_textsize	Size of the envfit text on the plot. (default: 3)
envfit_textcolor	Color of the envfit text on the plot. (default: "darkred")
envfit_numeric_arrows_scale	Scale the size of the numeric arrows. (default: 1)
envfit_arrowcolor	Color of the envfit arrows on the plot. (default: "darkred")
envfit_show	(logical) Show the results on the plot or not. (default: TRUE)
repel_labels	(logical) Repel all labels to prevent cluttering of the plot. (default: TRUE)
opacity	Opacity of all plotted points and sample_colorframe. 0: invisible, 1: opaque. (default: 0.8)
detailed_output	(logical) Return additional details or not (model, scores, inputmatrix, screeplot etc). If TRUE, it is recommended to save to an object and then access the additional data by View(object$data). (default: FALSE)
tax_empty	(ampvis2 only) How to show OTUs without taxonomic information. One of the following: "remove": Remove OTUs without taxonomic information. "best": (default) Use the best classification possible. "OTU": Display the OTU name.
...	Pass additional arguments to the vegan ordination functions, fx the rda, cca, metaMDS functions, see the documentation.

Details

A wrapper around the vegan package to generate ggplot2 ordination plots suited for analysis and comparison of microbial communities. Simply choose an ordination type and a plot is returned.

The vis_ordinate function is primarily based on two packages; vegan-package, which performs the actual ordination, and the ggplot2-package to generate the plot. The function generates an ordination plot by the following process:

1. Various input argument checks and error messages

2. Filtering, where low abundant variables across all samples are removed (if not filter_vars = 0 is set)

3. Data transformation (if not transform = "none" is set)

4. Calculate distance matrix based on the chosen distmeasure if the chosen ordination method is PCoA/nMDS/DCA

5. Perform the actual ordination and calculate the axis scores for both samples and variables

6. Visualise the result with ggplot2 or plotly in various ways defined by the user

Value

A ggplot2 object. If detailed_output = TRUE a list with a ggplot2 object and additional data.

Author(s)

Kasper Skytte Andersen [e-mail]

Thomas Yssing Michaelsen [e-mail]

Mads Albertsen [e-mail]

References

GUide to STatistical Analysis in Microbial Ecology (GUSTA ME): https://mb3is.megx.net/gustame

Legendre, Pierre & Legendre, Louis (2012). Numerical Ecology. Elsevier Science. ISBN: 9780444538680

Legendre, P., & Gallagher, E. (2001). Ecologically meaningful transformations for ordination of species data. Oecologia, 129(2), 271-280. http://doi.org/10.1007/s004420100716

See Also

mt_load

TYMichaelsen/mmtravis documentation built on Aug. 5, 2019, 10:48 a.m.