% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/main.r
\name{find_hvcs}
\alias{find_hvcs}
\title{Identifies and stores Highly Variable Cell Types (HVCs) in an
SummarizedExperiment object.}
\usage{
find_hvcs(se, variance_explained = 0.5, top_n_hvcs = NULL)
}
\arguments{
\item{se}{An initialized
\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}
object containing the CLR-transformed data in the \code{clr} assay.}

\item{variance_explained}{Numeric (default: 0.5). The target cumulative
proportion of total variance to be explained by the selected HVCs. The
function stops selecting cell types once this threshold is met.}

\item{top_n_hvcs}{Integer (optional). If provided, this overrides
\code{variance_explained} and selects exactly the top N cell types with the
highest variance.}
}
\value{
The updated
\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}
object with the following metadata populated:
\itemize{
\item \code{celltype_variances}: Data frame of cell type variances.
\item \code{variance_explained}: The exact variance proportion
captured by the selected HVCs.
\item \code{top_n_hvcs}: The number of HVCs selected.
\item \code{hvcs}: Character vector of the names
of the selected HVCs.
}
}
\description{
This function calculates the variance of each cell type across all samples
based on the Centered Log-Ratio (CLR) transformed data. It then selects the
subset of highly variable cell types (HVCs) that collectively explain a
specified proportion of the total variance, or a fixed number of top cell
types.
}
\examples{
data(example_data)
se <- ecoda(
    data = example_data$Gongsharma_full$cell_counts$authors_HR,
    metadata = example_data$Gongsharma_full$metadata
)

# Select HVCs that explain 75\% of the total variance
se <- find_hvcs(se, variance_explained = 0.75)

# Select exactly the top 5 most variable cell types
se <- find_hvcs(se, top_n_hvcs = 5)
}
\seealso{
\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment},
\code{\link{get_celltype_variances}}, \code{\link{get_hvcs}}
}
