Visualize Leading-Edge Genes from GSEA Results

Loads one or more GSEA result CSV files (from RunGSEA or RunGSEA_pseudobulk), searches for pathways by keyword or exact name, extracts the union of leading-edge genes, and produces a per-cell expression heatmap. Optionally, if a DEG data frame is supplied, the leading-edge genes are intersected with significant DEGs and additional diagnostic plots are produced (a second heatmap, dotplot, stacked violins, and boxplots).

Usage

VisualizeLeadingEdge(
  seurat_object,
  gsea_files,
  search_terms = NULL,
  pathways = NULL,
  group.by,
  split.by = NULL,
  assay = "RNA",
  layer = "data",
  min_expr = 0.05,
  subset_cells = FALSE,
  subset_by = NULL,
  subset_values = NULL,
  deg_df = NULL,
  deg_gene_column = "feature",
  deg_group_column = "group",
  deg_fc_column = "logFC",
  deg_padj_column = "padj",
  deg_padj_cutoff = 0.05,
  deg_top_n = 20,
  add_dotplot = TRUE,
  add_violin = TRUE,
  add_boxplots = TRUE,
  add_pvalues = TRUE,
  add_feature_maps = FALSE,
  heatmap_type = c("cell", "group"),
  heatmap_column_split = NULL,
  show_pathway_annotation = TRUE,
  group_colors = NULL,
  split_colors = NULL,
  heatmap_params = list(row_names_side = "left", show_row_dend = FALSE,
    row_names_max_width = grid::unit(15, "cm")),
  output_dir,
  object_name = "Analysis",
  subset_name = ""
)

Arguments

seurat_object: A Seurat object.
gsea_files: Character vector of CSV file paths (output of RunGSEA or RunGSEA_pseudobulk). Must each contain pathway and leadingEdge columns.
search_terms: Keyword(s) to filter pathways. See Pathway search above.
pathways: Exact pathway names to select (alternative to search_terms).
group.by: Metadata column for the primary grouping (required). Used for column annotation, dotplot, and violin grouping.
split.by: Optional second metadata column for column annotation and violin splitting.
assay: Assay to pull expression from (default "RNA").
layer: Layer to pull expression from (default "data").
min_expr: Genes whose row-mean expression is below this threshold are excluded from the heatmap (default 0.05).
subset_cells: Logical; if TRUE, subset seurat_object to subset_values in subset_by before analysis.
subset_by: Metadata column used for subsetting (requires subset_cells = TRUE).
subset_values: Character vector of values to retain in subset_by.
deg_df: Optional DEG data frame (e.g. from presto or FindMarkers). When provided, leading-edge genes are intersected with significant DEGs and additional plots are generated.
deg_gene_column: Column in deg_df with gene names (default "feature").
deg_group_column: Column in deg_df with group labels (default "group").
deg_fc_column: Column in deg_df with log-fold change (default "logFC").
deg_padj_column: Column in deg_df with adjusted p-value (default "padj").
deg_padj_cutoff: Adjusted p-value cut-off (default 0.05).
deg_top_n: Top N DEGs per group (by logFC) for bonus plots (default 20).
add_dotplot: Logical; produce a Seurat::DotPlot of top DEGs (default TRUE; requires deg_df).
add_violin: Logical; produce stacked violin plots of top DEGs (default TRUE; requires deg_df).
add_boxplots: Logical; produce boxplots of top DEGs (default TRUE; requires deg_df).
add_pvalues: Logical; overlay Kruskal-Wallis p-value on boxplots via ggpubr::stat_compare_means (default TRUE).
add_feature_maps: Logical; produce per-gene FeaturePlot PDFs for the top DEG genes (default FALSE; can be slow for large gene sets).
heatmap_type: Character. Either "cell" (default) for a per-cell heatmap with cells ordered by group.by (then split.by), or "group" for a compact group-mean heatmap with one column per group.by x split.by combination.
heatmap_column_split: Character or NULL. Metadata column used to split heatmap columns into labeled sections (e.g. a diagnosis or timepoint variable). Only applies when heatmap_type = "cell". Default NULL.
show_pathway_annotation: Logical. When TRUE (default), a colored annotation bar is drawn on the right of each heatmap showing which source pathway each gene belongs to. Suppressed automatically when only one pathway is matched.
group_colors: Named character vector of colors for group.by levels. Auto-assigned from Nour_pal("all") if NULL.
split_colors: Named character vector of colors for split.by levels. Auto-assigned from Nour_pal("spectrum") if NULL.
heatmap_params: Named list of additional arguments forwarded to ComplexHeatmap::Heatmap(). Any key supplied here overrides the default.
output_dir: Directory where all output files are saved.
object_name: Label used in output file names and subfolder (default "Analysis").
subset_name: Optional label appended to output file names (default "").

Value

Invisibly returns a named list:

genes_all: All leading-edge genes present in the Seurat object (after min_expr filtering).
genes_top: Top DEG genes within the leading edge, or NULL if no deg_df was provided.
top_degs: Filtered DEG data frame, or NULL.

Pathway search

search_terms as a character vector: OR logic - any term matches, case-insensitive.
search_terms as a list of character vectors: Each element is an AND-group (all terms must appear in the same pathway name); results are OR'd across elements.
pathways: Exact pathway names (alternative to search_terms).

Usage

Arguments

Value

Pathway search

See also