% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_variance_propagation.R
\name{plot_variance_propagation}
\alias{plot_variance_propagation}
\title{Variance propagation diagnostic for rarefaction}
\usage{
plot_variance_propagation(
  physeq_obj,
  rarefied,
  q = 0,
  group_var,
  group_color,
  convert_to_factor = FALSE
)
}
\arguments{
\item{physeq_obj}{Raw phyloseq object}

\item{rarefied}{Output from multi_rarefy(). Either a list of dataframes or and array.}

\item{q}{Hill number order (q = 0 for richness, q = 1 for Shannon, q = 2 for Simpson)}

\item{group_var}{A grouping variable to use gor grouping as in the sample_data()}

\item{group_color}{A color variable to use present in the sample_data()}

\item{convert_to_factor}{Logical. If \code{TRUE}, both \code{group_var} and
\code{group_color} are coerced to \code{factor} before plotting, which is
useful when those columns are numeric/continuous (e.g. dates, counts) but
should be treated as discrete groups. When \code{TRUE} a discrete color
scale (\code{scale_color_viridis_d}) is used; otherwise the continuous
scale (\code{scale_color_viridis_c}) is used. Default \code{FALSE}.}
}
\value{
ggplot object comparing raw vs rarefied diversity distributions across iterations.
}
\description{
This function evaluate the variance between rarefaction iterations from \code{multi_rarefy()} by visually comparing raw vs. rarefied alpha diversity metrics calculated at each iterations. It is possible to plot observed richness (q=0), Shannon diversity (q=1), or Simpson diversity (q=2) by setting the \code{q} parameter to "richness" or \code{q} = 0, "shannon" or \code{q} = 1, or "shannon" or \code{q} = 2. The plot is faceted by method (raw vs rarefied) and colored by a specified grouping variable from the sample data.
}
\examples{
library(phyloseq)
library(BRCore)
# Example comparing hill q=1 between Poplar and Switchgrass plots
bcse_filt <- bcse |>
subset_samples(Crop \%in\% c("Poplar", "Switchgrass"))

bcse_rarefied_otutable_filt <-
 multi_rarefy(
       physeq_obj = bcse_filt,
       depth_level = 1000,
       num_iter = 10,
       .as = "list",
       set_seed = 7643
   )

plot_variance_propagation(
   physeq_obj   = bcse_filt,
   rarefied = bcse_rarefied_otutable_filt,
   q        = 1,
   group_var = "Crop",
   group_color = "Plot"
)

}
