% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gsea.R
\name{GSEASummaryPlot}
\alias{GSEASummaryPlot}
\alias{GSEAPlot}
\title{GSEA summary dot plot}
\usage{
GSEASummaryPlot(
  data,
  in_form = c("auto", "dose", "fgsea"),
  gene_ranks = "@gene_ranks",
  gene_sets = "@gene_sets",
  top_term = 10,
  metric = "p.adjust",
  cutoff = 0.05,
  character_width = 50,
  line_plot_size = 0.25,
  metric_name = metric,
  nonsig_name = "Insignificant",
  linewidth = 0.2,
  line_by = c("prerank", "running_score"),
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  alpha = 0.6,
  aspect.ratio = 1,
  legend.position = "right",
  legend.direction = "vertical",
  theme = "theme_this",
  theme_args = list(),
  palette = "Spectral",
  palcolor = NULL,
  palreverse = FALSE,
  seed = 8525,
  ...
)

GSEAPlot(
  data,
  in_form = c("auto", "dose", "fgsea"),
  gene_ranks = "@gene_ranks",
  gene_sets = "@gene_sets",
  gs = NULL,
  sample_coregenes = FALSE,
  line_width = 1.5,
  line_alpha = 1,
  line_color = "#6BB82D",
  n_coregenes = 10,
  genes_label = NULL,
  label_fg = "black",
  label_bg = "white",
  label_bg_r = 0.1,
  label_size = 4,
  title = NULL,
  subtitle = NULL,
  xlab = NULL,
  ylab = NULL,
  combine = TRUE,
  nrow = NULL,
  ncol = NULL,
  byrow = TRUE,
  seed = 8525,
  axes = NULL,
  axis_titles = axes,
  guides = NULL,
  design = NULL,
  ...
)
}
\arguments{
\item{data}{A data frame.}

\item{in_form}{The format of the input data. See \code{\link{GSEASummaryPlot}}
for details.}

\item{gene_ranks}{A named numeric vector of gene-level rank statistics, with
gene identifiers as names. Used to construct the per-term line plots.
If a character string starting with \code{"@"}, the attribute of \code{data}
with that name (minus the \code{"@"}) is used as the gene ranks vector.}

\item{gene_sets}{A named list of gene sets. Each name must correspond to an
\code{ID} in \code{data}, and each element is a character vector of gene
identifiers. A GSEA ridge plot is generated for each gene set in the list.
If you only want to plot a subset of gene sets, subset the list before
passing it to this function. If a character string starting with
\code{"@"}, the attribute of \code{data} with that name (minus the
\code{"@"}) is used.}

\item{top_term}{Integer specifying the number of top terms to display, ranked
by \code{metric}. If \code{NULL}, all terms are shown.}

\item{metric}{Character string specifying the column name used to rank terms
and assess significance. Typically \code{"p.adjust"} or \code{"pvalue"}.
Terms are ranked by this column (ascending, lower is better) when
\code{top_term} is set. The same column is transformed to
\code{-log10(metric)} for the colour gradient.}

\item{cutoff}{Numeric threshold for the \code{metric} column. Terms with
values below this cutoff are coloured on a gradient; terms above are drawn
in grey (\code{"grey80"}) and labelled as insignificant via
\code{nonsig_name}. Default is \code{0.05}. If \code{NULL}, all terms are
treated as significant.}

\item{character_width}{Integer specifying the maximum character width for
wrapping term descriptions on the y-axis. Default is \code{50}.}

\item{line_plot_size}{Numeric controlling the size of the per-term miniature
enrichment plots embedded in each row. Expressed as a fraction of the plot
panel dimensions. Default is \code{0.25}.}

\item{metric_name}{Character string for the colour bar legend title.
Defaults to the value of \code{metric}.}

\item{nonsig_name}{Character string for the legend entry label used for
non-significant terms. Default is \code{"Insignificant"}.}

\item{linewidth}{Numeric specifying the line width within the per-term
miniature enrichment plots. Default is \code{0.2}.}

\item{line_by}{The method used to compute the per-term line plots:
\itemize{
\item{\code{"prerank"} (default): Use the gene ranks as the bar heights
(raw ranking metric).}
\item{\code{"running_score"}: Use the running enrichment score computed
by \code{gsea_running_score()}.}
}}

\item{title}{A character string specifying the title of the plot.
A function can be used to generate the title based on the default title.
This is useful when split_by is used and the title needs to be dynamic.}

\item{subtitle}{A character string specifying the subtitle of the plot.}

\item{xlab}{A character string specifying the x-axis label.}

\item{ylab}{A character string specifying the y-axis label.}

\item{alpha}{A numeric value specifying the transparency of the plot.}

\item{aspect.ratio}{A numeric value specifying the aspect ratio of the plot.}

\item{legend.position}{A character string specifying the position of the legend.
if \code{waiver()}, for single groups, the legend will be "none", otherwise "right".}

\item{legend.direction}{A character string specifying the direction of the legend.}

\item{theme}{A character string or a theme class (i.e. ggplot2::theme_classic) specifying the theme to use.
Default is "theme_this".}

\item{theme_args}{A list of arguments to pass to the theme function.}

\item{palette}{A character string specifying the palette to use.
A named list or vector can be used to specify the palettes for different \code{split_by} values.}

\item{palcolor}{A character string specifying the color to use in the palette.
A named list can be used to specify the colors for different \code{split_by} values.
If some values are missing, the values from the palette will be used (palcolor will be NULL for those values).}

\item{palreverse}{A logical value indicating whether to reverse the palette. Default is FALSE.}

\item{seed}{A numeric seed for reproducibility. Passed to
\code{\link{validate_common_args}()}.}

\item{...}{Additional arguments.}

\item{gs}{Character vector of gene set \code{ID}s to plot. If \code{NULL}
(default), all gene sets in \code{gene_sets} that appear in \code{data$ID}
are plotted.}

\item{sample_coregenes}{Logical; if \code{TRUE}, core enrichment genes are
sampled randomly for labelling. If \code{FALSE} (default), the first
\code{n_coregenes} core enrichment genes are used.}

\item{line_width}{Numeric specifying the line width for the running
enrichment score curve. Default is \code{1.5}.}

\item{line_alpha}{Numeric alpha transparency for the running score line and
hit indicator bars. Default is \code{1}.}

\item{line_color}{Character string specifying the colour of the running
enrichment score line. Default is \code{"#6BB82D"}.}

\item{n_coregenes}{Integer specifying the number of core enrichment genes to
label on the running score plot. Default is \code{10}. Ignored when
\code{genes_label} is provided.}

\item{genes_label}{Character vector of specific gene names to label on the
running score plot. When provided, \code{n_coregenes} is ignored.}

\item{label_fg}{Character string specifying the text colour of gene labels.
Default is \code{"black"}.}

\item{label_bg}{Character string specifying the background colour of gene
labels. Default is \code{"white"}.}

\item{label_bg_r}{Numeric specifying the corner radius of the label
background. Default is \code{0.1}.}

\item{label_size}{Numeric specifying the font size of the label text.
Default is \code{4}.}

\item{combine}{Logical; when \code{TRUE} (default), returns a combined
\code{patchwork} object. When \code{FALSE}, returns a named list of
individual \code{patchwork} objects (one per gene set).}

\item{ncol, nrow}{Integer number of columns / rows for the combined layout
(passed to \code{\link{combine_plots}()}).}

\item{byrow}{Logical; fill the combined layout by row. Default \code{TRUE}
(passed to \code{\link{combine_plots}()}).}

\item{axes}{A character string specifying how axes should be treated across
the combined layout (passed to \code{\link{combine_plots}()}).}

\item{axis_titles}{A character string specifying how axis titles should be
treated across the combined layout. Defaults to \code{axes}.}

\item{guides}{A character string specifying how guides (legends) should be
collected across panels (passed to \code{\link{combine_plots}()}).}

\item{design}{A custom layout design for the combined plot (passed to
\code{\link{combine_plots}()}).}
}
\value{
A \code{ggplot} object with \code{height} and \code{width}
attributes (in inches) attached.

A \code{patchwork} object when \code{combine = TRUE}, or a named
list of \code{patchwork} objects when \code{combine = FALSE}. Each
individual plot has \code{height} and \code{width} attributes in inches.
}
\description{
Produces a summary dot plot of GSEA (Gene Set Enrichment Analysis) results.
Each row represents a gene set (term), positioned along the x-axis by its
Normalized Enrichment Score (NES). Dot colour encodes the significance level
(typically \code{-log10(p.adjust)}) on a continuous gradient, and each row
includes a miniature line plot showing the gene ranks or running enrichment
score for that term's gene set.

The function supports both \code{DOSE} and \code{fgsea} package output
formats via the \code{in_form} parameter. Terms can be ranked and selected
by a significance metric (\code{top_term}, \code{metric}), with
non-significant terms rendered in grey. The per-term line plots can show
either the raw preranked gene statistics (\code{line_by = "prerank"}) or
the running enrichment score (\code{line_by = "running_score"}).
}
\examples{
\donttest{
data(gsea_example)

# Default summary dot plot with preranked gene statistics
GSEASummaryPlot(gsea_example)

# Use running enrichment score for per-term line plots
GSEASummaryPlot(gsea_example, line_by = "running_score")

# Raise the significance cutoff (all terms are coloured)
GSEASummaryPlot(gsea_example, cutoff = 0.01)
}
\donttest{
data(gsea_example)

# Single gene set
GSEAPlot(gsea_example, gene_sets = attr(gsea_example, "gene_sets")[1])

# Multiple gene sets arranged in a grid
GSEAPlot(gsea_example, gene_sets = attr(gsea_example, "gene_sets")[1:4])
}
}
