% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plotting.r
\name{plot_barplot}
\alias{plot_barplot}
\title{Generates a Stacked Bar Plot of Cell Type Relative Abundance.}
\usage{
plot_barplot(
  se,
  label_col = NULL,
  plot_by = c("sample", "group"),
  custom_sample_order = NULL,
  title = "",
  facet_by_label_col = TRUE
)
}
\arguments{
\item{se}{A
\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}
object containing cell type relative frequencies in the \code{freq} assay.}

\item{label_col}{Character string (optional, default: \code{NULL}). The name
of a column in \code{colData(se))} used to define grouping or groups
(required if \code{plot_by = "group"}).}

\item{plot_by}{Character string (default: \code{"sample"}). Specifies whether
to plot the relative abundance for each individual sample (\code{"sample"})
or the average relative abundance aggregated by a group (\code{"group"})
defined by \code{label_col}.}

\item{custom_sample_order}{Character vector (optional, default: \code{NULL}).
A vector of sample IDs to enforce a specific order when \code{plot_by =
  "sample"}. If \code{NULL}, samples are ordered first by \code{label_col}
(if provided) and then naturally.}

\item{title}{Character string (default: \code{""}). The main title for the
plot.}

\item{facet_by_label_col}{Logical (default: \code{TRUE}). If \code{TRUE} and
\code{plot_by = "sample"}, the plot will be faceted (split) horizontally by
the categories in \code{label_col}.}
}
\value{
A \code{ggplot} object representing the stacked bar plot.
}
\description{
This function visualizes the relative abundance (composition) of cell types
across samples or across aggregated groups. It automatically handles data
preparation and ordering based on the provided parameters.
}
\examples{
data(example_data)
se <- ecoda(
    data = example_data$Zhang$cell_counts$authors_LR,
    metadata = example_data$Zhang$metadata,
)

plot_barplot(se)

# Plotting average cell type abundance by experimental group
plot_barplot(
    se,
    label_col = "Tissue",
    plot_by = "group",
    title = "Mean Relative Abundance by Condition"
)

# Plotting cell type abundance for each sample separately
plot_barplot(
    se,
    label_col = "Tissue",
    plot_by = "sample",
    title = "Relative Abundance for Each Sample"
)
}
\seealso{
\code{\link{create_long_data}},
\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}
}
