% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/amp_core.R
\name{amp_core}
\alias{amp_core}
\title{Grouped core community analysis}
\usage{
amp_core(
  data,
  group_by,
  core_pct = 80,
  margin_plots = "xy",
  margin_plot_values_size = 3,
  widths = c(5, 1),
  heights = c(1, 5)
)
}
\arguments{
\item{data}{(\emph{required}) Data list as loaded with \code{\link{amp_load}}.}

\item{group_by}{(\emph{required}) Character vector of one or more variable name(s) in the sample metadata which contain the desired grouping of samples, fx where the samples have been taken. Can also be done by sample, just provide the name of the first variable containing unique sample ID's if so.}

\item{core_pct}{Threshold in percent for defining "abundant" a.k.a. "core" OTU's for each group. (\emph{default:} \code{80})}

\item{margin_plots}{Character vector defining which margin plots to show. Margin plots display the cumulative read abundances of all OTU's per group sharing either x or y axis with the main plot. Any of:
\itemize{
   \item \code{"x"}: Only show x axis margin plot.
   \item \code{"y"}: Only show y axis margin plot.
   \item \code{"xy"} (\emph{default}): Show both x and y margin plots.
   \item \code{""} or \code{NULL} (or anything else): Don't show any margin plots.
   }}

\item{margin_plot_values_size}{The size of the values indicated in the margin plots on top of the bars. Set to \code{0} to disable. (\emph{default:} \code{3})}

\item{widths}{Numeric vector with relative widths of the main and y margin plots. (\emph{default:} \code{c(5,1)})}

\item{heights}{Numeric vector with relative widths of the main and x margin plots. (\emph{default:} \code{c(1,5)})}
}
\value{
If no margin plots a \code{ggplot} object, otherwise a list with ggplot objects.
}
\description{
Core community plot to investigate how many of the most abundant OTU's comprise the "core" of groups of samples, their abundances etc.
}
\details{
This analysis only makes sense without aggregating OTU's to any taxonomic level, or else it will be biased by taxonomy and only be done on OTU's that have been classified, which is rarely all.
}
\section{Saving plot with \code{\link[ggplot2]{ggsave}}}{

When any margin plots are generated \code{\link{amp_core}} returns a list of ggplot objects to allow adjusting themes etc. of the individual subplots. The list is of class \code{coreplot} and a matching print function for the S3 class then stitches together the individual plots using the \href{https://patchwork.data-imaginist.com/}{patchwork} package. Therefore to save the plot with \code{\link[ggplot2]{ggsave}} simply pass on the plot object explicitly and wrap it in print(), see examples. This is not necessary if no margin plots are generated, as the returned object is then a regular ggplot object.
}

\examples{
# load example data
data("MiDAS")

# generate core analysis plot grouped by WWTP
plot <- amp_core(
  data = MiDAS,
  group_by = "Plant",
  core_pct = 80,
  margin_plots = "xy",
  margin_plot_values_size = 0 # set to 0 to not show values in margin plots
)

# adjust axes manually
plot$mainplot <- plot$mainplot +
  scale_x_discrete(breaks = seq(from = 0, to = 36, by = 5)) +
  scale_y_discrete(breaks = seq(from = 0, to = 36, by = 5))
plot$marginplot_x <- plot$marginplot_x + scale_x_discrete(breaks = seq(from = 0, to = 36, by = 5))
plot$marginplot_y <- plot$marginplot_y + scale_x_discrete(breaks = seq(from = 0, to = 36, by = 5))

# show plot
plot

# To save the plot with ggsave() wrap the plot object in print()
# ggsave("plot.png", print(plot))
}
\references{
Marta Nierychlo, Kasper Skytte Andersen, Yijuan Xu, Nicholas Green, Chenjing Jiang, Mads Albertsen, Morten Simonsen Dueholm, Per HalkjÃ¦r Nielsen (2020): "MiDAS 3: An ecosystem-specific reference database, taxonomy and knowledge platform for activated sludge and anaerobic digesters reveals species-level microbiome composition of activated sludge", Water Research, Volume 182. \doi{10.1016/j.watres.2020.115955}
Saunders, Aaron M; Albertsen, Mads; Vollertsen, Jes; Nielsen, Per H (2016): "The activated sludge ecosystem contains a core community of abundant organisms", ISME Journal 10, 11-20. \doi{10.1038/ismej.2015.117}
}
\seealso{
\code{\link{amp_load}}
}
\author{
Kasper Skytte Andersen \email{ksa@bio.aau.dk}

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