kaleidocell.run_gsea_pipeline#

kaleidocell.run_gsea_pipeline(mp_results, gsea_sets=None, from_file=None, custom_set=None, translation_file=None, method='enrichr', permutation_num=1000, seed=42, fdr_threshold=0.25, min_size=5, max_size=500, output_csv='gsea_terms_only.csv', top_n_plot=6, plot=False, save_csv=False)[source]#

Run the full GSEA workflow for all meta-programs.

For each MP, runs either Enrichr (over-representation) or preranked GSEA (using gene loading weights as ranking scores), collects significant terms, and optionally saves a CSV and shows bar plots.

Parameters:

  • mp_results (dict) – Output of derive_nmf_metaprograms().

  • gsea_sets (str or list, optional) – Named Enrichr libraries.

  • from_file (str or list of str, optional) – Paths to GMT/CSV gene-set files.

  • custom_set (dict, pd.DataFrame, or str, optional) – Custom gene-set input.

  • translation_file (str, None, or False) –

    Controls Ensembl → HGNC translation.

    None (default)

    Auto-detect: if the MP gene names look like Ensembl IDs (≥ 50 % start with ENSG), the bundled hgnc_ensembl_translation.txt is loaded automatically and genes are translated before being passed to GSEA. No action is taken when genes already appear to be HGNC symbols.

    str

    Path to a custom two-column TSV (HGNC, Ensembl_ID) used regardless of auto-detection.

    False

    Disable translation entirely.

  • method ({"enrichr", "prerank"}, default "enrichr") –

    Statistical method to use.

    "enrichr"

    Passes the MP’s gene list to Enrichr. Fast and suitable for named online libraries. Does not use gene weights.

    "prerank"

    Passes the full ranked gene list (genes sorted by their consensus loading weight) to gseapy’s GSEA prerank algorithm. Uses weight information continuously, not just the presence/absence of a gene in the set. Requires a local gene-set file (from_file) or dict (custom_set) — named online Enrichr libraries are not supported by prerank.

  • permutation_num (int, default 1000) – Number of permutations (prerank only).

  • seed (int, default 42) – Random seed for reproducibility (prerank only).

  • fdr_threshold (float, default 0.25) – FDR q-value cutoff for significance (prerank only). The conventional GSEA threshold is 0.25; use 0.05 for stricter filtering. For "enrichr" the threshold is fixed at 0.05 on the Adjusted P-value.

  • min_size (int, default 5) – Minimum gene-set size to test (prerank only).

  • max_size (int, default 500) – Maximum gene-set size to test (prerank only).

  • output_csv (str, default "gsea_terms_only.csv") – Filename for the significant-terms CSV.

  • top_n_plot (int, default 6) – Number of top terms per MP shown in bar plots.

  • plot (bool, default False) – Display bar plots inline.

  • save_csv (bool, default False) – Write the significant-terms table to output_csv.

Returns:

  • terms_df (pd.DataFrame) – Significant terms across all MPs. Columns for "enrichr": MP, Term. Columns for "prerank": MP, Term, NES, FDR q-val.

  • mp_plot_data (dict) – {mp_name: pd.DataFrame} formatted for plot_gsea_results().

Return type:

tuple[DataFrame, dict]

Examples

Enrichr (default):

>>> terms_df, mp_plot_data = kaleidocell.run_gsea_pipeline(
...     results_mp, from_file="h.all.v2026.1.Hs.symbols.gmt"
... )

Preranked GSEA using loading weights:

>>> terms_df, mp_plot_data = kaleidocell.run_gsea_pipeline(
...     results_mp,
...     from_file="h.all.v2026.1.Hs.symbols.gmt",
...     method="prerank",
...     fdr_threshold=0.25,
... )