% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plotting.r
\name{plot_boxplot}
\alias{plot_boxplot}
\title{Generates Boxplots for CLR-transformed Cell Type Abundances with Optional
Group Comparison.}
\usage{
plot_boxplot(
  se,
  assay = c("clr", "clr_hvc", "asin_sqrt"),
  label_col = NULL,
  selected_celltypes = NULL,
  title = "",
  stat_method = "wilcox.test",
  paired = FALSE,
  signif_label = c("p.signif", "p.format")
)
}
\arguments{
\item{se}{An
\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}
object containing the CLR-transformed abundances in the \code{clr}.}

\item{assay}{Character string (default: \code{"clr"}). The name of the assay
in the \code{SummarizedExperiment} object to use for plotting. 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)) or \code{"asin_sqrt"} (arcsin-square root transformed data).}

\item{label_col}{Character string (optional, default: \code{NULL}). The name
of a column in \code{colData(se)} used to define groups for comparison. If
\code{NULL}, a single boxplot is generated per cell type.}

\item{selected_celltypes}{Specify selected celltypes you want to plot instead
of plotting boxplots for all. Note: this does not recalculate CLR-values on
subset.}

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

\item{stat_method}{Character string (default: \code{"wilcox.test"}). The
statistical method used for comparisons between 2 groups (e.g., "t.test",
"wilcox.test"). Note: This is overridden by "kruskal.test" for 3+ groups.}

\item{paired}{Logical (default: \code{FALSE}). If \code{TRUE}, performs a
paired statistical test (e.g., paired t-test or paired Wilcoxon test). Only
applicable for 2-group comparisons.}

\item{signif_label}{Character string (default: \code{"p.signif"}). Controls
how p-values are displayed for 2-group comparisons (e.g., "p.signif" for
stars, "p.format" for numeric p-value).}
}
\value{
A \code{ggplot} object (enhanced by \code{ggpubr}) representing the
CLR abundance boxplot, including jittered data points and dynamic
significance information (pairwise stars for 2 groups, overall p-value for
3+ groups).
}
\description{
This function visualizes the distribution of CLR-transformed abundance for
each cell type using boxplots, optionally splitting the data by a sample
metadata column and performing statistical tests for comparison between
groups.
}
\details{
\strong{Statistical Test Logic:}
\itemize{
\item If the number of groups (\code{label_col} levels) is \strong{2}, the
function uses the specified \code{stat_method}
(default: "wilcox.test") and displays pairwise significance labels
or stars.
\item If the number of groups is \strong{3 or more}, and
\code{stat_method} is "wilcox.test" or "t.test", the function
automatically switches to the global non-parametric test,
\strong{"kruskal.test"}, and displays the overall p-value
for the comparison across all groups.
}
}
\examples{
data(example_data)
se <- ecoda(
    data = example_data$Zhang$cell_counts$authors_LR,
    metadata = example_data$Zhang$metadata,
)

# 1. Boxplots for CLR abundance without grouping (no stats calculated):
plot_boxplot(se)

# 2. Boxplots grouped by 'Treatment' (2 groups) and applying Wilcoxon test:
plot_boxplot(
    se,
    label_col = "Tissue",
    stat_method = "wilcox.test",
    title = "CLR Abundance by Tissue (with Wilcoxon Test)"
)
}
\seealso{
\code{\link{create_long_data}},
\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}
}
