Skip to contents

GSEA Running Score Mountain Plots - Direct or from RunGSEA Output Directory

PlotGSEAEnrichment.Rd

Two operating modes:

Direct mode - pass fgsea_result and ranked_stats directly (e.g. from an ad-hoc fgsea run or a single CSV).

RunGSEA directory mode - point to the output_dir of a completed RunGSEA run via gsea_dir. The function auto-discovers all CSV files, searches pathway names with keyword search (same AND/OR logic as RunSCssGSEA), loads the ranked AUC vectors from the cached DE RDS files, and produces a grid layout:

  • One PDF per split.by level (cell type) - each PDF may have multiple pages when there are more groups than max_cols

  • Columns = group.by levels (comparison groups, e.g. Male / Female) - up to max_cols per page; additional groups wrap to new pages

  • Rows = matched pathways (one 3-panel mountain stack per pathway)

Usage

PlotGSEAEnrichment(
  fgsea_result = NULL,
  ranked_stats = NULL,
  gsea_dir = NULL,
  database = NULL,
  search_terms = NULL,
  pathways = NULL,
  top_n = 5,
  label_levels = NULL,
  group_levels = NULL,
  split_levels = NULL,
  max_cols = 6,
  colors = c(pos = "#B40426", neg = "#3B4CC0"),
  ncol = 1,
  output_dir = NULL,
  object_name = "",
  subset_name = "",
  file_name = NULL,
  width = NULL,
  height = NULL,
  timestamp = FALSE
)

Arguments

fgsea_result

Direct mode only. Data frame with fgsea output or a path to a single RunGSEA CSV. Must have pathway, NES, leadingEdge, and size columns.

ranked_stats

Direct mode only. Named numeric vector (gene → AUC or logFC), sorted descending.

gsea_dir

RunGSEA directory mode. Path to the output_dir used in RunGSEA.

database

Database subfolder name (e.g. "Hallmark", "C2"). NULL uses the first database found.

search_terms

Keyword search for pathways - same AND/OR logic as RunSCssGSEA: a character vector applies OR; a list of character vectors applies AND within each element, OR across elements. Case-insensitive.

pathways

Exact pathway names to plot (alternative to search_terms).

top_n

Direct mode only. When neither pathways nor search_terms is given, plot the top N by |NES|. Default 5.

label_levels

RunGSEA directory mode. Which label.by levels to include. NULL = all.

group_levels

RunGSEA directory mode. Which group.by (cluster) levels to include as pages. NULL = all.

split_levels

RunGSEA directory mode. Which split.by (cell type) levels to include as pages. NULL = all.

max_cols

RunGSEA directory mode. Maximum number of group.by levels (columns) per page. When the total number of groups exceeds this value the groups are chunked across multiple pages within the same PDF. Default 6.

colors

Named vector with "pos" (positive NES) and "neg" (negative NES) color entries. Default red / blue.

ncol

Direct mode only. Number of columns in the output layout. Default 1.

output_dir

Directory to save PDFs. NULL = no save.

object_name

Label prefix for output file names.

subset_name

Optional subset label.

file_name

Character or NULL. Base name (no extension) for the saved PDF. Only applies in direct mode, which saves one combined PDF; RunGSEA directory mode can save several PDFs per call (one per pathway x label combination) so an explicit override isn't applied there. NULL (default) auto-deduces from object_name and subset_name.

width, height

Numeric or NULL. Override the auto-calculated PDF dimensions in inches. NULL (default) auto-sizes to the pathway grid.

timestamp

Logical. When TRUE, append a _YYYYMMDD-HHMMSS stamp to every saved file name so repeated runs are versioned instead of overwriting the previous PDF(s). Default FALSE.

Value

Direct mode: a single patchwork object. RunGSEA directory mode: invisibly, a nested list [[lab]][[cl]][[pw]][[sp]] of mountain-plot patchwork objects; PDFs are written to output_dir (one per lab×cl combination).

See also

RunGSEA, RunEnrichment