% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/amp_ordinate.R
\name{amp_ordinate}
\alias{amp_ordinate}
\title{Ordination plot}
\usage{
amp_ordinate(
  data,
  filter_species = 0.1,
  type = "PCA",
  distmeasure = "bray",
  transform = "hellinger",
  constrain = NULL,
  x_axis = 1,
  y_axis = 2,
  print_caption = FALSE,
  sample_color_by = NULL,
  sample_color_order = NULL,
  sample_shape_by = NULL,
  sample_colorframe = FALSE,
  sample_colorframe_label = NULL,
  sample_colorframe_label_size = 3,
  sample_label_by = NULL,
  sample_label_size = 4,
  sample_label_segment_color = "black",
  sample_point_size = 2,
  sample_trajectory = NULL,
  sample_trajectory_group = NULL,
  sample_plotly = NULL,
  species_plot = FALSE,
  species_nlabels = 0,
  species_label_taxonomy = "Genus",
  species_label_size = 3,
  species_label_color = "grey10",
  species_rescale = FALSE,
  species_point_size = 2,
  species_shape = 20,
  species_plotly = FALSE,
  envfit_factor = NULL,
  envfit_numeric = NULL,
  envfit_signif_level = 0.005,
  envfit_textsize = 3,
  envfit_textcolor = "darkred",
  envfit_numeric_arrows_scale = 1,
  envfit_arrowcolor = "darkred",
  envfit_show = TRUE,
  repel_labels = TRUE,
  opacity = 0.8,
  tax_empty = "best",
  detailed_output = FALSE,
  num_threads = 1L,
  ...
)
}
\arguments{
\item{data}{(\emph{required}) Data list as loaded with \code{\link{amp_load}}.}

\item{filter_species}{Remove low abundant OTU's across all samples below this threshold in percent. Setting this to 0 may drastically increase computation time. (\emph{default}: \code{0.1})}

\item{type}{(\emph{required}) Type of ordination method. One of:
\itemize{
   \item \code{"PCA"}: (\emph{default}) Principal Components Analysis
   \item \code{"RDA"}: Redundancy Analysis (considered the constrained version of PCA)
   \item \code{"CA"}: Correspondence Analysis
   \item \code{"CCA"}: Canonical Correspondence Analysis (considered the constrained version of CA)
   \item \code{"DCA"}: Detrended Correspondence Analysis
   \item \code{"NMDS"}: non-metric Multidimensional Scaling
   \item \code{"PCOA"} or \code{"MMDS"}: metric Multidimensional Scaling a.k.a Principal Coordinates Analysis (not to be confused with PCA)
   }
   \emph{Note that PCoA is not performed by the vegan package, but the \code{\link[ape]{pcoa}} function from the APE package.}}

\item{distmeasure}{(\emph{required for nMDS and PCoA}) Distance measure used for the distance-based ordination methods (nMDS and PCoA). Choose one of the following:
\itemize{
  \item \code{"wunifrac"} (PCoA only): Weighted UniFrac distances. Requires a rooted phylogenetic tree.
  \item \code{"unifrac"} (PCoA only): Unweighted UniFrac distances. Requires a phylogenetic tree.
  \item \code{"jsd"} (PCoA only): Jensen-Shannon Divergence, based on \url{http://enterotype.embl.de/enterotypes.html}.
  \item Any of the distance measures supported by \code{\link[vegan]{vegdist}}: \code{"manhattan"}, \code{"euclidean"}, \code{"canberra"}, \code{"bray"}, \code{"kulczynski"}, \code{"gower"}, \code{"morisita"}, \code{"horn"}, \code{"mountford"}, \code{"jaccard"}, \code{"raup"}, \code{"binomial"}, \code{"chao"}, \code{"altGower"}, \code{"cao"}, \code{"mahalanobis"}, \code{"clark"}, \code{"chisq"}, \code{"chord"}, \code{"hellinger"}, \code{"aitchison"}, \code{"robust.aitchison"}.
 }
You can also write your own math formula, see details in \code{\link[vegan]{vegdist}}.
Default is \code{bray}.}

\item{transform}{(\emph{recommended}) Transforms the abundances before ordination, choose one of the following: \code{"total"}, \code{"max"}, \code{"freq"}, \code{"normalize"}, \code{"range"}, \code{"standardize"}, \code{"pa"} (presence/absense), \code{"chi.square"}, \code{"hellinger"}, \code{"log"}, or \code{"sqrt"}, see details in \code{\link[vegan]{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. (\emph{default:} \code{"hellinger"})}

\item{constrain}{(\emph{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 \code{c("Year", "Temperature")}, but keep in mind that the more variables selected the more the result will be similar to unconstrained analysis.}

\item{x_axis}{(\emph{integer}) Which axis from the ordination results to plot as the first axis. Have a look at the \code{$screeplot} with \code{detailed_output = TRUE} to validate axes. With nMDS the number of dimensions (\code{k} argument to the \code{\link[vegan]{metaMDS}} function) is set to that of the highest number of either \code{x_axis} or \code{y_axis}. (\emph{default:} \code{1})}

\item{y_axis}{(\emph{integer}) Which axis from the ordination results to plot as the second axis. Have a look at the \code{$screeplot} with \code{detailed_output = TRUE} to validate axes. With nMDS the number of dimensions (\code{k} argument to the \code{\link[vegan]{metaMDS}} function) is set to that of the highest number of either \code{x_axis} or \code{y_axis}. (\emph{default:} \code{2})}

\item{print_caption}{Auto-generate a figure caption based on the arguments used. The caption includes a description of how the result has been generated as well as references for the methods used.}

\item{sample_color_by}{Color sample points by a variable in the metadata.}

\item{sample_color_order}{Order the colors in \code{sample_color_by} by the order in a vector.}

\item{sample_shape_by}{Shape sample points by a variable in the metadata.}

\item{sample_colorframe}{Frame the sample points with a polygon by a variable in the metadata split by the variable defined by \code{sample_color_by}, or simply \code{TRUE} to frame the points colored by \code{sample_color_by}. (\emph{default:} \code{FALSE})}

\item{sample_colorframe_label}{Label by a variable in the metadata.}

\item{sample_colorframe_label_size}{Size of the color frame labels. (\emph{default:} \code{3})}

\item{sample_label_by}{Label sample points by a variable in the metadata.}

\item{sample_label_size}{Sample labels text size. (\emph{default:} \code{4})}

\item{sample_label_segment_color}{Sample labels repel-segment color. (\emph{default:} \code{"black"})}

\item{sample_point_size}{Size of the sample points. (\emph{default:} \code{2})}

\item{sample_trajectory}{Make a trajectory between sample points by a variable in the metadata.}

\item{sample_trajectory_group}{Make a trajectory between sample points by the \code{sample_trajectory} argument, but within individual groups.}

\item{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 \code{"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 \code{plotly::layout(amp_ordinate(...), showlegend = FALSE)}, see more options at \url{https://plot.ly/r/}.}

\item{species_plot}{(\emph{logical}) Plot species points or not. (\emph{default:} \code{FALSE})}

\item{species_nlabels}{Number of the most extreme species labels to plot (ordered by the sum of the numerical values of the x,y coordinates. Only makes sense with PCA/RDA).}

\item{species_label_taxonomy}{Taxonomic level by which to label the species points. (\emph{default:} \code{"Genus"})}

\item{species_label_size}{Size of the species text labels. (\emph{default:} \code{3})}

\item{species_label_color}{Color of the species text labels. (\emph{default:} \code{"grey10"})}

\item{species_rescale}{(\emph{logical}) Rescale species points or not. Basically they will be multiplied by 0.8, for visual convenience only. (\emph{default:} \code{FALSE})}

\item{species_point_size}{Size of the species points. (\emph{default:} \code{2})}

\item{species_shape}{The shape of the species points, fx \code{1} for hollow circles or \code{20} for dots. (\emph{default:} \code{20})}

\item{species_plotly}{(\emph{logical}) Enable interactive species points so that they can be hovered to show complete taxonomic information. (\emph{default:} \code{FALSE})}

\item{envfit_factor}{A vector of categorical environmental variables from the metadata to fit onto the ordination plot. See details in \code{\link[vegan]{envfit}}.}

\item{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 \code{\link[vegan]{envfit}}.}

\item{envfit_signif_level}{The significance threshold for displaying the results of \code{envfit_factor} or \code{envfit_numeric}. (\emph{default:} \code{0.005})}

\item{envfit_textsize}{Size of the envfit text on the plot. (\emph{default:} \code{3})}

\item{envfit_textcolor}{Color of the envfit text on the plot. (\emph{default:} \code{"darkred"})}

\item{envfit_numeric_arrows_scale}{Scale the size of the numeric arrows. (\emph{default:} \code{1})}

\item{envfit_arrowcolor}{Color of the envfit arrows on the plot. (\emph{default:} \code{"darkred"})}

\item{envfit_show}{(\emph{logical}) Show the results on the plot or not. (\emph{default:} \code{TRUE})}

\item{repel_labels}{(\emph{logical}) Repel all labels to prevent cluttering of the plot. (\emph{default:} \code{TRUE})}

\item{opacity}{Opacity of all plotted points and sample_colorframe. \code{0}: invisible, \code{1}: opaque. (\emph{default:} \code{0.8})}

\item{tax_empty}{How to show OTUs without taxonomic information. One of the following:
\itemize{
   \item \code{"remove"}: Remove OTUs without taxonomic information.
   \item \code{"best"}: (\emph{default}) Use the best classification possible.
   \item \code{"OTU"}: Display the OTU name.
   }}

\item{detailed_output}{(\emph{logical}) Return additional details or not (model, scores, figure caption, inputmatrix, screeplot etc). If \code{TRUE}, it is recommended to save to an object and then access the additional data by \code{View(object$data)}. (\emph{default:} \code{FALSE})}

\item{num_threads}{The number of threads to use whereever in the code parallelisation is possible. Any parallel computation is being performed by using \code{\link[foreach]{foreach}}. (\emph{default:} \code{1})}

\item{...}{Pass additional arguments to the vegan ordination functions, fx the \code{\link[vegan]{rda}}, \code{\link[vegan]{cca}}, \code{\link[vegan]{metaMDS}} functions, see the documentation.}
}
\value{
A ggplot2 object. If \code{detailed_output = TRUE} a list with a ggplot2 object and additional data.
}
\description{
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.
}
\details{
The \code{\link{amp_ordinate}} function is primarily based on two packages; \code{\link[vegan]{vegan-package}}, which performs the actual ordination, and the \code{\link[ggplot2]{ggplot2-package}} to generate the plot. The function generates an ordination plot by the following process:
\enumerate{
  \item Various input argument checks and error messages
  \item OTU-table filtering, where low abundant OTU's across all samples are removed (if not \code{filter_species = 0} is set)
  \item Data transformation (if not \code{transform = "none"} is set)
  \item Calculate distance matrix based on the chosen \code{distmeasure} if the chosen ordination method is PCoA/nMDS/DCA
  \item Perform the actual ordination and calculate the axis scores for both samples and species/OTU's
  \item Visualise the result with ggplot2 or plotly in various ways defined by the user
}

When the chosen ordination method is an eigenanalysis-based method then the relative contribution (eigenvalue) of each axis to the total inertia in the data (sum of all eigenvalues, including those of the constrained space) is indicated in percent at the axis titles. When one of the constrained ordination methods (\code{RDA} and \code{CCA}) is used then a second value is furthermore shown which then indicates the relative contribution of the particular axis to the total constrained space only.
}
\section{Using a custom distance matrix}{

If you wan't to calculate a distance matrix manually and use it for PCoA or nMDS in \code{amp_ordinate}, it can be done by setting \code{filter_species = 0}, \code{transform = "none"}, \code{distmeasure = "none"}, and then override the abundance table (\code{$abund}) in the ampvis2 object, like below. The matrix must be a symmetrical matrix containing coefficients for all pairs of samples in the data.
\preformatted{
#Override the abundance table in the ampvis2 object with a custom distance matrix
ampvis2_object$abund <- custom_dist_matrix
#set filter_species = 0, transform = "none", and distmeasure = "none"
amp_ordinate(ampvis2_object,
             type = "pcoa",
             filter_species = 0,
             transform = "none",
             distmeasure = "none")
}
}

\examples{
# Load example data
data("AalborgWWTPs")

# PCA with data transformation, colored by WWTP
amp_ordinate(AalborgWWTPs,
  type = "PCA",
  transform = "hellinger",
  sample_color_by = "Plant",
  sample_colorframe = TRUE
)
\dontrun{
# Interactive CCA with data transformation constrained to seasonal period
amp_ordinate(AalborgWWTPs,
  type = "CCA",
  transform = "Hellinger",
  constrain = "Period",
  sample_color_by = "Period",
  sample_colorframe = TRUE,
  sample_colorframe_label = "Period",
  sample_plotly = "all"
)
}
}
\references{
GUide to STatistical Analysis in Microbial Ecology (GUSTA ME): \url{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. \doi{10.1007/s004420100716}
}
\seealso{
\code{\link{amp_load}}
}
\author{
Kasper Skytte Andersen \email{ksa@bio.aau.dk}

Mads Albertsen \email{MadsAlbertsen85@gmail.com}
}
