% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/amp_filter_samples.R
\name{amp_filter_samples}
\alias{amp_filter_samples}
\alias{amp_subset_samples}
\title{Subset ampvis2 objects based on sample metadata}
\usage{
amp_filter_samples(
  data,
  ...,
  minreads = 0,
  rarefy = NULL,
  normalise = FALSE,
  removeAbsentOTUs = TRUE
)

amp_subset_samples(
  data,
  ...,
  minreads = 0,
  rarefy = NULL,
  normalise = FALSE,
  removeAbsentOTUs = TRUE
)
}
\arguments{
\item{data}{(\emph{required}) Data list as loaded with \code{\link{amp_load}}.}

\item{...}{Logical expression indicating elements or rows to keep in the metadata. Missing values are treated as \code{FALSE}. Passed directly to \code{\link[dplyr]{filter}}.}

\item{minreads}{Minimum number of reads pr. sample. Samples below this value will be removed \emph{initially}. (\emph{default:} \code{0})}

\item{rarefy}{Rarefy species richness to this value by using \code{\link[vegan]{rrarefy}}. This is done \emph{initially}, but \emph{after} filtering based on the \code{minreads} value, if set. (\emph{default:} \code{NULL})}

\item{normalise}{(\emph{logical}) Normalise the OTU read counts to 100 (ie percent) per sample \emph{BEFORE} the subset. (\emph{default:} \code{FALSE})}

\item{removeAbsentOTUs}{(\emph{logical}) Whether to remove OTU's that may have 0 read abundance in all samples after the subset. (\emph{default:} \code{TRUE})}
}
\value{
A modifed ampvis2 object
}
\description{
Subsets the data in ampvis2 objects based on metadata and returns the subsetted object.
}
\details{
The subset is performed on the metadata by \code{subset()} and the abundance- and taxonomy tables are then adjusted accordingly.
}
\section{Preserving relative abundances in a subset of larger data}{

By default the raw read counts in the abundance matrix are normalised (transformed to percentages) by some plotting functions automatically (for example \code{\link{amp_heatmap}}, \code{\link{amp_timeseries}}, and more). This means that the relative abundances shown will be calculated based on the remaining taxa after the subset, not including the removed taxa, if any. To circumvent this, set \code{normalise = TRUE} when subsetting with the \code{\link{amp_filter_taxa}} and \code{\link{amp_filter_samples}} functions, and then set \code{normalise = FALSE} in the plotting function. This will transform the OTU counts to relative abundances BEFORE the subset, and setting \code{normalise = FALSE} will skip the transformation in the plotting function, see the example below.

\preformatted{
data("MiDAS")
subsettedData <- amp_filter_samples(MiDAS,
                                    Plant \%in\% c("Aalborg West", "Aalborg East"),
                                    normalise = TRUE
                                    )
amp_heatmap(subsettedData,
            group_by = "Plant",
            tax_aggregate = "Phylum",
            tax_add = "Genus",
            normalise = FALSE
            )
}
}

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

# Show a short summary about the data by simply typing the name of the object in the console
MiDAS

# Keep only samples containing Aalborg West or East in the Plant column
MiDASsubset <- amp_filter_samples(MiDAS, Plant \%in\% c("Aalborg West", "Aalborg East"))

# Summary
MiDASsubset

# Keep only samples containing Aalborg West or East in the Plant column
# and remove the sample "16SAMP-749". Remove any sample(s) with less than 20000 total reads
MiDASsubset2 <- amp_filter_samples(MiDAS,
  Plant \%in\% c("Aalborg West", "Aalborg East") & !SampleID \%in\% c("16SAMP-749"),
  minreads = 20000
)

# Summary
MiDASsubset2
}
\references{
McMurdie, P.J. & Holmes, S. (2014). Waste not, want not: Why
rarefying microbiome data is inadmissible. \emph{PLoS Comput Biol}
\strong{10(4):} e1003531. DOI:\code{10.1371/journal.pcbi.1003531}
}
\seealso{
\code{\link{amp_load}}, \code{\link{amp_filter_taxa}}
}
\author{
Kasper Skytte Andersen \email{ksa@bio.aau.dk}

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