% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/identify_core.R
\name{identify_core}
\alias{identify_core}
\title{Identify Core Microbiome Using Bray-Curtis Similarity
biological samples. Core taxa are selected using either a "last \% increase"
or "elbow" method implementing the method developed by Shade
and Stopnisek (2019) Curr Opin Microbiol, see below for details.}
\usage{
identify_core(
  physeq_obj,
  rarefied_list = NULL,
  priority_var,
  increase_value = 0.02,
  abundance_weight = 0,
  max_otus = NULL,
  depth_level = 1000,
  seed = NULL
)
}
\arguments{
\item{physeq_obj}{A \code{phyloseq} object with at least \code{otu_table} and
\code{sample_data}.
If the \code{phyloseq} object is already rarefied (i.e., all samples have the
same sequencing depth), you can omit \code{rarefied_list} and the function will
automatically use the OTU table from \code{physeq_obj} as a single iteration. If
the data is not rarefied, you must provide a \code{rarefied_list} generated by
\code{multi_rarefy}. Alternatively you can use \code{update_otu_table} to replace the
OTU table with a rarefied version before running \code{identify_core}.}

\item{rarefied_list}{A list of data frames, each representing a rarefied OTU
table (taxa x samples) generated by \code{multi_rarefy}. Required if \code{physeq_obj}
is not already rarefied. If \code{physeq_obj} is rarefied, this can be omitted
and the function will use the OTU table from \code{physeq_obj} as a single
iteration.}

\item{priority_var}{The column name in the \code{sample_data} (e.g.
sampling_date", "site") that is used for prioritizing the core microbiome.}

\item{increase_value}{Increase value (numeric, scalar) used in the
calculation (default 0.02) for "increase". The "elbow" is always calculated
and returned as \code{elbow_core} (see below for details).}

\item{abundance_weight}{Numeric in \verb{[0,1]}; how much to weight mean relative
abundance in the ranking score. \code{0} (default) uses occupancy/composite only.
\code{1} ranks purely by abundance. Values in between blend the two (e.g.,
abundance_weight = 0.3 gives 70\% occupancy/composite + 30\% abundance).}

\item{max_otus}{Optional integer to limit analysis to the top N ranked OTUs.
If NULL (default), all OTUs are analyzed. Useful for large datasets
(>5000 OTUs)}

\item{depth_level}{Integer. The sequencing depth used for normalization in
Bray-Curtis calculations. If data is rarefied, this is automatically set
to the rarefaction depth. For unrarefied data, samples with depth below
this threshold are excluded from pairwise comparisons.}

\item{seed}{Optional integer to set the RNG seed for reproducibility.}
}
\value{
A list with:
\itemize{
\item \code{bray_curtis_ranked} tibble with \code{rank}, mean Bray-Curtis
similarity across sample pairs (\code{MeanBC}) at each cumulative \code{rank},
normalized proportion (\code{proportionBC}), the multiplicative \code{IncreaseBC},
and the elbow metric (\code{elbow_slope_diffs}).
(\code{proportionBC}), the multiplicative \code{IncreaseBC}, and the elbow metric
(\code{elbow_slope_diffs}).
\item \code{otu_ranked} tibble with ranked OTU/ASVs .
\item \code{abundance_occupancy} tibble with OTU/ASVs names, occupancy
(\code{otu_occ}), and mean relative abundance (\code{otu_rel}).
\item \code{priority_var} character, the variable used for prioritizing
the core.
\item \code{elbow} core set identified by elbow method (integer).
\item \code{bc_increase} core set identified by last \% BC-increase
(integer).
\item \code{increase_value} increase value (numeric, scalar) used in the
calculation (e.g. 0.02).
\item \code{elbow_core} core OTU/ASVs using elbow method (character
vector).
\item \code{increase_core} core OTU/ASVs using last \% BC-increase method
(character vector).
\item \code{otu_table} otu_table counts (otu x samples) used (data.frame).
\item \code{sample_metadata} samples metadata (data.frame).
\item \code{taxonomy_table} taxonomy if present (data.frame); otherwise
NULL.
}
}
\description{
Identify Core Microbiome Using Bray-Curtis Similarity
biological samples. Core taxa are selected using either a "last \% increase"
or "elbow" method implementing the method developed by Shade
and Stopnisek (2019) Curr Opin Microbiol, see below for details.
}
\details{
The core set is defined using two separate methods:

The function rank OTU/ASVs by occupancy (optionally with abundance
weighting: \code{rank_score = (1 - weight) * rank + weight * scaled_abundance},
where scaled_abundance is mean relative abundance rescaled to \verb{[0,1]}). For
each \verb{k = 1..K}, recompute \code{S_k} as the mean Bray-Curtis similarity across
all sample pairs using only the first \code{k} ranked OTUs; when \code{k = K}, this
yields \code{S_K}, the value computed with all OTUs. Normalizing by \code{S_K}
gives \code{C_k = S_k / S_K}.

The \strong{elbow} is the point of diminishing returns: for each \code{k}, compare the
average \emph{left} slope \code{(S_k - S_1) / (k - 1)} to the average \emph{right} slope
\code{(S_K - S_k) / (K - k)}, and choose the \code{k} that maximizes \code{(left - right)}.

The \strong{last percent Bray-Curtis increase} method uses the same accumulation
curve, examine the multiplicative step when adding the \code{k-th} OTU:
\verb{Increase_k = S_k / S_\{k-1\}} (equivalently, \verb{Increase_k = C_k / C_\{k-1\}}).
Choose the largest \code{k} such that \code{Increase_k >= 1 + p}, where \code{p} is your
chosen percent threshold (increase_value; recommended \code{p >= 0.02} or \verb{2\%}).
This selects the final rank for which adding one more taxon still increases
the explained Bray-Curtis similarity by at least \code{p}.
}
\section{Dependencies}{

Requires \pkg{phyloseq}, \pkg{dplyr}, \pkg{tidyr}, \pkg{tibble}, \pkg{rlang},
and \pkg{vegan}.
}

\examples{
\donttest{
library(BRCore)

# With rarefied data
res <- identify_core(
  physeq_obj     = switchgrass,
  priority_var   = "sampling_date",
  increase_value = 0.02,
  seed           = 091825
)

str(res)

# With unrarefied data (requires multi_rarefy step)
rarefied_list <- multi_rarefy(
  physeq_obj = bcse,
  depth_level = 1000,
  num_iter = 3,
  .as = "list",
  set_seed = 7642
)


res_rare <- identify_core(
  physeq_obj = bcse,
  rarefied_list = rarefied_list,
  priority_var = "Crop",
  increase_value = 0.02,
  seed = 091825
)

str(res_rare)
}

}
\references{
Shade A, Stopnisek N (2019) Abundance-occupancy
distributions to prioritize plant core microbiome membership. Current
Opinion in Microbiology, 49:50-58
\url{doi:10.1016/j.mib.2019.09.008}
}
\seealso{
\code{\link[=multi_rarefy]{multi_rarefy()}}, \code{\link[=plot_identified_core]{plot_identified_core()}}, and
\code{\link[=plot_core_distribution]{plot_core_distribution()}}
}
