scatrans.run_enrichment

Contents

scatrans.run_enrichment#

scatrans.run_enrichment(gene_list, gene_sets, universe=None, background=None, adata=None, pval_cutoff=None, padj_cutoff=None, min_size=5, max_size=500, restrict_background_to_gene_sets=True, force_universe=False, return_all=False, verbose=True, organism='mouse', gene_case=None, gene_set_source='scatrans', include_gene_list=False, p_adjust_method='fdr_bh', **kwargs)[source]#

Hypergeometric over-representation analysis (clusterProfiler-style ORA).

Background / universe handling is designed to be close to clusterProfiler’s enricher / enrichGO default conservative behavior: - If you provide a universe (or background for compat), by default it is

intersected with the genes that appear in the gene_sets (i.e. have annotation). This matches clusterProfiler’s default (see issues #283/#636).

  • Set restrict_background_to_gene_sets=False or force_universe=True to use the user-provided list untouched (analogous to clusterProfiler’s options(enrichment_force_universe = TRUE)).

  • If neither provided, universe = union of all genes present in the gene_sets (safe default, similar to clusterProfiler when no universe given).

New smart default (recommended): - If you do not pass universe or background, but you pass an adata on which

scat.store_raw_counts(adata) was previously called, run_enrichment will automatically use the preserved full measured gene list (adata.uns[“scatrans”][“raw_gene_list”]) as the background. This is the safest and most convenient behavior for single-cell data.

  • Explicit universe=… or background=… always takes precedence.

Historical note on universe: Passing universe=adata.var_names.tolist() after HVG subsetting is usually wrong. The background should be the genes that were actually measured in the experiment.

Returned DataFrame is rich: clusterProfiler-compatible columns + RichFactor, string helpers, TermSize, neg_log10_padj, plus detailed .attrs[“universe_info”] and other diagnostics (including gene_set_info and reason on empty results).

gene_listlist-like, pd.Series, or pd.DataFrame

Genes to test for over-representation. Besides plain lists, accepts DE / filter output tables with gene symbols in the index (all_results, significant, filter_active_genes(...)), or explicit gene / names columns.

pval_cutoff / padj_cutofffloat

Cutoff applied to adjusted p-values (p.adjust column), NOT raw p-values. IMPORTANT: Despite the name, pval_cutoff filters on the BH-adjusted p-value. - Preferred: use padj_cutoff explicitly. - pval_cutoff is deprecated for new code (warning emitted when used alone). Default 0.05. If both passed, padj_cutoff wins.

gene_set_source{“scatrans”, “enrichr”}, default “scatrans”

Explicit override for which family to use. - “scatrans” (default): Prefer the bundled scATrans / clusterProfiler-derived sets. - “enrichr”: Force the original Enrichr/gseapy libraries.

In most cases you do not need this parameter: - Default behavior uses the package’s bundled sets (only organism needed for run_kegg). - To pick a specific Enrichr historical version, just write the exact name

(e.g. gene_sets=”GO_Biological_Process_2021” or kegg_library=”KEGG_2021”). Names containing year suffixes are automatically treated as Enrichr requests.

The parameter is mainly for forcing one side when the auto-detection would choose differently.

include_gene_listbool, default False

If True, include an additional “Genes_list” column containing Python lists of the overlapping genes (in addition to the semicolon-joined “Genes” string). Useful for in-memory Python workflows; “Genes” remains for CSV/export compat.

p_adjust_method{“fdr_bh”, “bonferroni”, “none”}, default “fdr_bh”

Multiple-testing correction applied across all tested terms in this call (including when a custom dict mixes GO/KEGG/custom pathways). For multi-cluster comparisons use compare_enrichment(..., adjust_across_clusters=True).

backgroundoptional

Deprecated alias of universe. Use universe instead. If both are provided, raises ValueError. In docs and examples we strongly prefer the term universe.

Parameters:
Return type:

DataFrame

Contents