scatrans.run_gsea

Contents

scatrans.run_gsea#

scatrans.run_gsea(ranked_genes, gene_sets, min_size=15, max_size=500, nperm=1000, organism='mouse', gene_case=None, gene_set_source='scatrans', verbose=True, seed=42, threads=4, ascending=False, weight=None, weighted_score_type=None, score_column=None, **kwargs)[source]#

Pre-ranked Gene Set Enrichment Analysis (GSEA) using gseapy.prerank.

This implements the classic GSEA algorithm on a user-provided ranked gene list (e.g. logFC, t-statistic or custom score from active_score / DE results). It is the Python equivalent of clusterProfiler::GSEA / Broad GSEA Preranked.

Parameters:

  • ranked_genes (pd.Series, dict, DataFrame, or list-like) –

    • Preferred: pd.Series with gene names as index and numeric scores as values. Higher score = more “up” in target group (e.g. logFC). The function will sort internally if needed.

    • pd.DataFrame from active_score / differential_expression all_results: gene symbols in the index, numeric score in a column (auto-prefers logFC, then active_score). Use score_column= to override.

    • Legacy DataFrame: two columns [gene_names, scores] with a default RangeIndex.

    • dict: gene -> score

    • list of genes: treated as pre-sorted from high to low (scores assigned decreasing).

    Gene names will be cleaned according to gene_case.

  • score_column (str, optional) – When ranked_genes is a DataFrame, which column holds the ranking metric. Defaults to logFC, then active_score, then the sole numeric column.

  • gene_sets (str, dict or list) – Same as run_enrichment: bundled name (e.g. “GO_Biological_Process”), GMT path, dict of term->genes, or Enrichr library name.

  • min_size (int) – Minimum / maximum number of genes in a gene set to consider.

  • max_size (int) – Minimum / maximum number of genes in a gene set to consider.

  • nperm (int) – Number of permutations for p-value estimation.

  • organism (str) – “mouse” or “human” (used for Enrichr/gseapy library lookup).

  • gene_case ({"upper", "lower", None}) – Case normalization for gene symbols (same as other enrichment functions).

  • gene_set_source ({"scatrans", "enrichr"}) – Control source preference (same semantics as run_enrichment).

  • verbose (bool) – Print progress.

  • seed (int) – Random seed forwarded to gseapy.prerank (reproducible permutations).

  • threads (int) – CPU threads for gseapy prerank.

  • ascending (bool) – If True, lower ranked metric = more enriched (gseapy convention).

  • weight (float, optional) – GSEA enrichment weight passed to gseapy (Broad p exponent; default 1.0 = weighted).

  • weighted_score_type (str or float, optional) – Deprecated alias for weight. Broad/GSEA naming: "classic" → 0.0 (unweighted KS); "weighted" → 1.0. When omitted, defaults to weighted (1.0).

  • **kwargs – Additional arguments forwarded to gseapy.prerank (e.g. graph_num).

Returns:

GSEA results with columns including Term, Description, ES, NES, pvalue, p.adjust, neg_log10_padj, leading_edge, etc. Sorted by |NES| (absolute value) descending so that the strongest magnitude effects (positive or negative) appear first. Rich metadata in .attrs (method=”gsea_prerank”, gene_set_info, nperm, gsea_info, analysis_info).

Return type:

pd.DataFrame

Notes

  • Unlike ORA, GSEA does not use an explicit “universe” in the same way; the ranked list itself defines the background. min_size/max_size still apply.

  • Requires gseapy. Install via pip install gseapy or pip install “scatrans[gsea]”.

  • all_results from active_score can be passed directly::

    res = scat.run_gsea(all_results, gene_sets=”GO_Biological_Process”, score_column=”logFC”)

    or as a Series: all_results["logFC"] (index = gene names).

Contents