% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plotting.r
\name{plot_heatmap}
\alias{plot_heatmap}
\title{Generates a Heatmap of Cell Abundance Data from an SummarizedExperiment
assay.}
\usage{
plot_heatmap(
  se,
  assay = c("clr", "counts", "counts_imp", "freq", "freq_imp", "asin_sqrt", "clr_hvc",
    "pb"),
  label_col,
  cluster_rows = TRUE,
  cluster_cols = TRUE,
  scale = "none",
  clustering_method = "ward.D2",
  angle_col = "90",
  ...
)
}
\arguments{
\item{se}{A
\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}
object.}

\item{assay}{Character string (default: \code{"clr"}). The name of the assay
in the \code{SummarizedExperiment} object to use for the heatmap. Must be
one of: \code{"clr"} (CLR-transformed abundances, default),
\code{"clr_hvc"} (CLR-transformed abundances of only the most highly
variable cell types (HVCs)), \code{"pb"} (pseudobulk gene expression),
\code{"counts"} (raw counts), \code{"counts_imp"} (imputed counts),
\code{"freq"} (relative frequencies), \code{"freq_imp"} (imputed
frequencies), or \code{"asin_sqrt"} (arcsin-square root transformed data).}

\item{label_col}{Character string. The name of the column in
\code{colData(se)} to use for annotating the samples (columns) of the
heatmap.}

\item{cluster_rows}{Logical (default: \code{TRUE}). Whether to apply
hierarchical clustering to the cell types (rows).}

\item{cluster_cols}{Logical (default: \code{TRUE}). Whether to apply
hierarchical clustering to the samples (columns).}

\item{scale}{Character string (default: \code{"none"}). Method for scaling
the abundance values within the heatmap using \code{pheatmap}. Options
include \code{"none"}, \code{"row"}, or \code{"column"}. Note: The data is
internally \strong{mean-centered} (\code{scale(center=TRUE, scale=FALSE)})
across samples before being passed to \code{pheatmap}, regardless of this
argument.}

\item{clustering_method}{Character string (default: \code{"ward.D2"}). The
clustering method to use for hierarchical clustering. Options are passed
directly to \code{hclust} (e.g., \code{"complete"}, \code{"average"},
\code{"ward.D2"}).}

\item{angle_col}{Character string (default: \code{"90"}). Angle of the sample
labels (columns).}

\item{...}{Additional arguments passed directly to the \code{pheatmap}
function.}
}
\value{
A \code{pheatmap} object, which is typically visualized automatically
when called interactively.
}
\description{
This function visualizes a data matrix from a specified slot (e.g.,
CLR-transformed, frequency, or pseudobulk data) after mean-centering. It
supports optional filtering to only Highly Variable Cell Types (HVCs) and
includes a sample annotation sidebar based on a specified metadata column.
}
\examples{
# Example for a simple dataset:
data(example_data)
se <- ecoda(
    data = example_data$Zhang$cell_counts$authors_LR,
    metadata = example_data$Zhang$metadata,
)

plot_heatmap(se, label_col = c("Clinical.efficacy.", "Tissue"))

plot_heatmap(
    se,
    label_col = c("Clinical.efficacy.", "Tissue"),
    # Additional arguments for pheatmap:
    cutree_rows = 3,
    cutree_cols = 3
)

# Example of a large cohort with 868 samples and 69 cell types
se <- ecoda(
    data = example_data$Gongsharma_full$cell_counts$authors_HR,
    metadata = example_data$Gongsharma_full$metadata
)

plot_heatmap(
    se,
    label_col = c("subject.cmv", "age_group"),
    cutree_rows = 3,
    cutree_cols = 5,
    show_colnames = FALSE
)

# Using only the most highly variable cell types (HVCs)
plot_heatmap(
    se,
    assay = "clr_hvc",
    label_col = c("subject.cmv", "age_group"),
    cutree_rows = 3,
    cutree_cols = 4,
    show_colnames = FALSE
)
}
\seealso{
\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment},
\code{\link[pheatmap]{pheatmap}}
}
