% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bdiv_table.r
\name{bdiv_table}
\alias{bdiv_table}
\alias{bdiv_matrix}
\alias{bdiv_distmat}
\title{Distance / dissimilarity between samples.}
\usage{
bdiv_table(
  biom,
  bdiv = "bray",
  weighted = NULL,
  normalized = NULL,
  tree = NULL,
  md = ".all",
  within = NULL,
  between = NULL,
  delta = ".all",
  norm = "none",
  pseudocount = NULL,
  power = 1.5,
  alpha = 0.5,
  transform = "none",
  ties = "random",
  seed = 0,
  cpus = n_cpus(),
  ...
)

bdiv_matrix(
  biom,
  bdiv = "bray",
  weighted = NULL,
  normalized = NULL,
  tree = NULL,
  within = NULL,
  between = NULL,
  norm = "none",
  pseudocount = NULL,
  power = 1.5,
  alpha = 0.5,
  transform = "none",
  ties = "random",
  seed = 0,
  cpus = n_cpus()
)

bdiv_distmat(
  biom,
  bdiv = "bray",
  weighted = NULL,
  normalized = NULL,
  tree = NULL,
  within = NULL,
  between = NULL,
  norm = "none",
  pseudocount = NULL,
  power = 1.5,
  alpha = 0.5,
  transform = "none",
  ties = "random",
  seed = 0,
  cpus = n_cpus()
)
}
\arguments{
\item{biom}{An \link[=rbiom_objects]{rbiom object}, or any value accepted by \code{\link[=as_rbiom]{as_rbiom()}}.}

\item{bdiv}{Beta diversity distance algorithm(s) to use. Options are:
\code{c("aitchison", "bhattacharyya", "bray", "canberra", "chebyshev",  "chord", "clark", "sorensen", "divergence", "euclidean",  "generalized_unifrac", "gower", "hamming", "hellinger", "horn",  "jaccard", "jensen", "jsd", "lorentzian", "manhattan", "matusita",  "minkowski", "morisita", "motyka", "normalized_unifrac", "ochiai",  "psym_chisq", "soergel", "squared_chisq", "squared_chord",  "squared_euclidean", "topsoe", "unweighted_unifrac",  "variance_adjusted_unifrac", "wave_hedges", "weighted_unifrac")}.
For the UniFrac family, a phylogenetic tree must be present in \code{biom}
or explicitly provided via \verb{tree=}. Supports partial matching.
Multiple values are allowed for functions which return a table or
plot. Default: \code{"bray"}}

\item{weighted}{(Deprecated - weighting is now inherent in bdiv metric name.)
Take relative abundances into account. When \code{weighted=FALSE}, only
presence/absence is considered. Multiple values allowed. Default: \code{NULL}}

\item{normalized}{(Deprecated - normalization is now inherent in bdiv metric
name.) Only changes the "Weighted UniFrac" calculation. Divides result by
the total branch weights. Default: \code{NULL}}

\item{tree}{A \code{phylo} object representing the phylogenetic
relationships of the taxa in \code{biom}. Only required when
computing UniFrac distances. Default: \code{biom$tree}}

\item{md}{Dataset field(s) to include in the output data frame, or \code{'.all'}
to include all metadata fields. Default: \code{'.all'}}

\item{within, between}{Dataset field(s) for intra- or inter- sample
comparisons. Alternatively, dataset field names given elsewhere can
be prefixed with \code{'=='} or \code{'!='} to assign them to \code{within} or
\code{between}, respectively. Default: \code{NULL}}

\item{delta}{For numeric metadata, report the absolute difference in values
for the two samples, for instance \code{2} instead of \code{"10 vs 12"}.
Default: \code{TRUE}}

\item{norm}{Normalize the incoming counts. Options are:
\itemize{
\item \code{'none'}: No transformation.
\item \code{'percent'}: Relative abundance (sample abundances sum to 1).
\item \code{'binary'}: Unweighted presence/absence (each count is either 0 or 1).
\item \code{'clr'}: Centered log ratio.
}

Default: \code{'none'}.}

\item{pseudocount}{Value added to counts to handle zeros when
\code{norm = 'clr'}. Ignored for other normalization methods.
Default: \code{NULL} (emits a warning).}

\item{power}{Scaling factor for the magnitude of differences between
communities (\eqn{p}) when \code{bdiv = 'minkowski'}. Ignored for other
beta diversity metrics. Default: \code{1.5}}

\item{alpha}{The alpha term to use in Generalized UniFrac. How much weight
to give to relative abundances; a value between 0 and 1, inclusive.
Setting \code{alpha=1} is equivalent to Normalized UniFrac. Default: \code{0.5}}

\item{transform}{Transformation to apply to calculated values. Options are:
\code{c("none", "rank", "log", "log1p", "sqrt", "percent")}. \code{"rank"} is
useful for correcting for non-normally distributions before applying
regression statistics. Default: \code{"none"}}

\item{ties}{When \code{transform="rank"}, how to rank identical values.
Options are: \code{c("average", "first", "last", "random", "max", "min")}.
See \code{rank()} for details. Default: \code{"random"}}

\item{seed}{Random seed for permutations. Must be a non-negative integer.
Default: \code{0}}

\item{cpus}{The number of CPUs to use. Set to \code{NULL} to use all available,
or to \code{1} to disable parallel processing. Default: \code{NULL}}

\item{...}{Not used.}
}
\value{
\describe{
\item{\code{bdiv_matrix()} - }{ An R matrix of samples x samples. }
\item{\code{bdiv_distmat()} - }{ A dist-class distance matrix. }
\item{\code{bdiv_table()} - }{
A tibble data.frame with columns named .sample1, .sample2,
.bdiv, .distance, and any fields requested by \code{md}. Numeric metadata
fields will be returned as \code{abs(x - y)}; categorical metadata fields as
\code{"x"}, \code{"y"}, or \code{"x vs y"}. }
}
}
\description{
Distance / dissimilarity between samples.
}
\section{Metadata Comparisons}{


Prefix metadata fields with \code{==} or \code{!=} to limit comparisons to within or
between groups, respectively. For example, \code{stat.by = '==Sex'} will
run calculations only for intra-group comparisons, returning "Male" and
"Female", but NOT "Female vs Male". Similarly, setting
\code{stat.by = '!=Body Site'} will only show the inter-group comparisons, such
as "Saliva vs Stool", "Anterior nares vs Buccal mucosa", and so on.

The same effect can be achieved by using the \code{within} and \code{between}
parameters. \code{stat.by = '==Sex'} is equivalent to
\verb{stat.by = 'Sex', within = 'Sex'}.
}

\examples{
    library(rbiom)
    
    # Subset to four samples
    biom <- hmp50$clone()
    biom$counts <- biom$counts[,c("HMP18", "HMP19", "HMP20", "HMP21")]
    
    # Return in long format with metadata
    bdiv_table(biom, 'w_unifrac', md = ".all")
    
    # Only look at distances among the stool samples
    bdiv_table(biom, 'w_unifrac', md = c("==Body Site", "Sex"))
    
    # Or between males and females
    bdiv_table(biom, 'w_unifrac', md = c("Body Site", "!=Sex"))
    
    # All-vs-all matrix
    bdiv_matrix(biom, 'w_unifrac')
    
    # All-vs-all distance matrix
    dm <- bdiv_distmat(biom, 'w_unifrac')
    dm
    plot(hclust(dm))

}
\seealso{
Other beta_diversity: 
\code{\link{bdiv_boxplot}()},
\code{\link{bdiv_clusters}()},
\code{\link{bdiv_corrplot}()},
\code{\link{bdiv_heatmap}()},
\code{\link{bdiv_ord_plot}()},
\code{\link{bdiv_ord_table}()},
\code{\link{bdiv_stats}()},
\code{\link{distmat_stats}()}
}
\concept{beta_diversity}
