% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plotting.r
\name{calc_anosim}
\alias{calc_anosim}
\title{Analysis of Similarities (ANOSIM) R score}
\usage{
calc_anosim(dist_mat, labels, permutations = 99, parallel = 1, digits = 3)
}
\arguments{
\item{dist_mat}{Sample distance matrix.}

\item{labels}{Vector of factors or character strings. The grouping variable
(the known cluster assignments) for each row in the matrix.}

\item{permutations}{Integer (default: \code{99}). The number of permutations
to use when calculating the ANOSIM R-statistic and p-value.}

\item{parallel}{Integer (optional, default: \code{1}). The number
of parallel processes/cores to use for the permutation testing.}

\item{digits}{Integer (default: \code{3}). The number of decimal places to
round the R-statistic.}
}
\value{
A numeric value representing the \strong{ANOSIM R-statistic}.
}
\description{
Calculates the ANOSIM R-statistic to test whether there is
significant separation between two or more groups (defined by
\code{labels}) based on the sample distance matrix (\code{dist_mat}).
}
\details{
ANOSIM compares the mean of rank dissimilarities between groups to
the mean of rank dissimilarities within groups. The R-statistic ranges from
-1 to 1:
\itemize{
\item An R value close to \strong{1} indicates clear separation of groups.
\item An R value close to \strong{0} indicates that the separation is
no greater than expected by chance (i.e., poor separation).
\item An R value close to \strong{-1} indicates that within-group
dissimilarities are greater than between-group dissimilarities
(a very rare result).
}
}
\examples{
library(SummarizedExperiment)
data(example_data)
se <- ecoda(
    data = example_data$Gongsharma_full$cell_counts$authors_HR,
    metadata = example_data$Gongsharma_full$metadata
)

# Extract necessary components
dist_mat <- dist(t(assay(se, "clr")))
labels <- colData(se)$subject.cmv

# Run the calculation
calc_anosim(dist_mat, labels, parallel = 1)
}
