% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plotting.r
\name{plot_pca}
\alias{plot_pca}
\title{Plot Principal Component Analysis and Calculate Clustering Scores}
\usage{
plot_pca(
  se,
  assay = c("clr", "counts", "counts_imp", "freq", "freq_imp", "asin_sqrt", "clr_hvc",
    "pb"),
  label_col = NULL,
  scale. = FALSE,
  title = NULL,
  title_show_n_features = TRUE,
  legend_title = "Group",
  show_label_samples = FALSE,
  score_digits = 3,
  cluster_score = FALSE,
  mod_score = FALSE,
  sil_score = FALSE,
  anosim_score = TRUE,
  anosim_permutations = 99,
  anosim_parallel = 1,
  ari_nclusts = NULL,
  knn_k = 3,
  pointsize = 3,
  labelsize = 4,
  coord_equal = TRUE,
  axes = c(1, 2),
  invisible = c("var", "quali"),
  geom = "point",
  n_hv_feat_show = Inf,
  repel = TRUE
)
}
\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 PCA. 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 (optional, default: \code{NULL}). The name
of a column in \code{colData(sd)} used to color and group samples in the
plot, and for calculating clustering scores.}

\item{scale.}{Logical (default: \code{FALSE}). A value indicating whether the
variables should be scaled to have unit variance before the PCA.}

\item{title}{Character string (optional, default: \code{NULL}). The main
title for the plot. If clustering scores are calculated, they are appended
to this title.}

\item{title_show_n_features}{Logical (optional, default: \code{TRUE}) Show
the number of features (cell types or genes) used.}

\item{legend_title}{Character string (default: \code{"Group"}). The title for
the color legend in the plot when a grouping column (\code{label_col}) is
provided.}

\item{show_label_samples}{Logical (default: \code{FALSE}). If \code{TRUE},
sample names are displayed next to the points in the plot. This
automatically adds \code{"text"} to the \code{geom} parameter if it is not
already present.}

\item{score_digits}{Integer (default: \code{3}). The number of decimal places
to round the clustering and ANOSIM scores appended to the plot title.}

\item{cluster_score}{Logical (default: \code{TRUE}). If \code{TRUE},
calculates the Adjusted Rand Index (ARI) using \code{\link{calc_ari}}.}

\item{mod_score}{Logical (default: \code{TRUE}). If \code{TRUE}, calculates
the adjusted Modularity score using \code{\link{calc_modularity}}.}

\item{sil_score}{Logical (default: \code{FALSE}). If \code{TRUE}, calculates
the average Silhouette width using \code{\link{calc_sil}}.}

\item{anosim_score}{Logical (default: \code{TRUE}). If \code{TRUE},
calculates the ANOSIM statistic (R) using \code{vegan::anosim}.}

\item{anosim_permutations}{Integer (default: \code{99}). The number of
permutations to use when calculating the ANOSIM statistic.}

\item{anosim_parallel}{Integer (default: \code{1}). The number of parallel
processes/cores to use for the ANOSIM calculation.}

\item{ari_nclusts}{Integer (optional, default: \code{NULL}). The target
number of clusters (\code{k}) to use for \code{hclust} and \code{pam}. If
\code{NULL}, it defaults to the number of unique levels in \code{labels}.}

\item{knn_k}{Integer (optional, default: \code{3}). The number of nearest
neighbors (\code{k}) to use for the Shared Nearest Neighbor (SNN) graph
construction, required for Modularity score calculation. If \code{NULL}, it
defaults to \code{max(3, round(sqrt(N)))}, where \code{N} is the number of
samples.}

\item{pointsize}{Numeric (default: \code{3}). Size of the points in the plot.}

\item{labelsize}{Numeric (default: \code{4}). Size of the variable labels in
the plot.}

\item{coord_equal}{Logical (default: \code{TRUE}). If \code{TRUE}, forces the
aspect ratio of the plot to be equal.}

\item{axes}{Numeric vector (default: \code{c(1, 2)}). The principal
components to plot (e.g., \code{c(1, 2)} for PC1 vs PC2).}

\item{invisible}{Character vector (default: \code{c("var", "quali")}).
Elements to hide. Can include "var" (variables/cell types), "ind"
(samples), or "quali" (group centroids). see the description of
\link[factoextra:fviz_pca]{factoextra} for details.}

\item{geom}{Character string or vector (default: \code{"point"}). The
geometry to be used for the plot. Allowed values are combinations of:
\itemize{
\item \code{"point"} to show points for individuals (samples)
\item \code{"text"} to show labels for individuals (samples)
\item \code{"arrow"} to show vectors for variables (features)
}
The default \code{"point"} plots points for both individuals and variables.
Use \code{c("point", "text")} to show both points and labels for samples.}

\item{n_hv_feat_show}{Integer (default: \code{Inf}). Number of most highly
variable features to show based on their contribution to the selected axes.}

\item{repel}{Logical (default: \code{TRUE}). Whether to use \code{ggrepel} to
prevent label overlap for variable names.}
}
\value{
A \code{ggplot} object via \code{factoextra} visualizing the PCA
results.
}
\description{
Performs Principal Component Analysis (PCA) on a selected data
matrix from the \code{SummarizedExperiment} object (default:
CLR-transformed abundances, \code{clr}) and visualizes the results. It can
also calculate and display several metrics to evaluate the separation of
groups defined by \code{label_col}. It uses
\link[factoextra:fviz_pca]{factoextra}.
}
\details{
The clustering metrics (ARI, Modularity, Silhouette, ANOSIM) assess
how well the sample groupings (\code{labels}) align with the underlying
data structure in the feature space defined by the PCA.
}
\examples{
data(example_data)
se <- ecoda(
    data = example_data$Zhang$cell_counts$authors_LR,
    metadata = example_data$Zhang$metadata,
)

plot_pca(
    se,
    label_col = "Tissue",
    title = "PCA based on cell type composition",
    anosim_parallel = 1,
    n_hv_feat_show = 5 # Shows the most highly variable features (cell types)
)

# Using only the most highly variable cell types
plot_pca(
    se,
    assay = "clr_hvc",
    label_col = "Tissue",
    title = "PCA based on highly variable cell types",
    anosim_parallel = 1,
    n_hv_feat_show = nrow(S4Vectors::metadata(se)$clr_hvc)
)
}
