gseapy

GSEApy provides 7 main sub-commands for different enrichment analysis methods:

• gsea: Produces GSEA results. Requires a text file (FPKM, TPM, etc.), a .cls file, and a .gmt gene sets file.
• prerank: Produces Prerank tool results. Requires a pre-ranked gene list in .rnk format and a .gmt file. Supports the fgsea multilevel p-value method via method='multilevel'.
• ssgsea: Performs single sample GSEA (ssGSEA). Accepts pd.Series, pd.DataFrame (including .gct files), or .gct files for multiple samples.
• gsva: Performs GSVA method. Input format is the same as ssgsea.
• replot: Reproduces GSEA desktop version results using the location of the desktop output.
• enrichr: Wrapper for the Enrichr API for fast gene set enrichment.
• biomart: Converts gene IDs using the BioMart API.

Prerank (GSEA)

• Use case: Comparing two groups of samples (e.g., control vs. treatment).
• Input: A gene ranking defined by a custom method (e.g., t-statistic, signal-to-noise).
• Enrichment Score (ES): Calculated as the max(running enrichment scores) or min(running enrichment scores).

ssGSEA

• Use case: Comparing individual samples against the rest of the population to find shared gene signatures. Best used when you have a large number of samples.
• Enrichment Score (ES): Calculated as the sum(running enrichment scores).
• Note: The original ssGSEA algorithm does not provide p-values or FDR. Consequently, gseaplot generated by ssgsea will not show p-values or FDR.

You can install GSEApy using conda/mamba, pip, or uv.

Note: For GSEApy versions > 0.11.0, a Rust compiler is required for building. If pip installation fails, you should install the Rust toolchain first and then install via pip or uv.

# if you have conda/mamba
$ conda install -c bioconda gseapy

# or pip
$ pip install gseapy

# or uv
$ uv add gseapy

# If pip install failed, install rust first:
$ curl https://sh.rustup.rs -sSf | sh -s -- -y
$ export PATH="$PATH:$HOME/.cargo/bin"
$ pip install gseapy

The enrichr module requires a list of genes. You can provide this data in two ways:

1. A Python list object: A standard list of strings.
2. A text file: A .txt file containing one gene ID per row.

Important Requirements:

• Enrichr uses Entrez gene symbols as input.
• You must convert all gene names to uppercase.

Generated plots are compatible with all matplotlib figure formats, allowing for easy modification of .pdf files.

# Option 1: Using a Python list object
gene_list = ['SCARA3', 'LOC100044683', 'CMBL', 'CLIC6', 'IL13RA1', 'TACSTD2', 'DKKL1', 'CSF1', 'CITED1', 'SYNPO2L']

# Option 2: Using a text file (one gene per line)
# The file content should look like:
# CTLA2B
# SCARA3
# ...

To save plots generated by gseaplot, barplot, dotplot, or heatmap to a file (e.g., PDF) while working in a Jupyter notebook, use the ofname argument.

gseaplot(..., ofname='your.plot.pdf')

When working in Jupyter or when you have custom gene sets, the gene_sets argument in several APIs accepts a Python dict. This allows you to define your own terms and their corresponding gene lists directly in your code without needing an external GMT file.

Supported APIs for dictionary input:

• gsea
• prerank
• ssgsea
• enrichr

gene_sets = {
    "term_1": ["gene_A", "gene_B", ...],
    "term_2": ["gene_B", "gene_C", ...],
    "term_100": ["gene_A", "gene_T", ...]
}

GSEAbase is the base class for GSEA implementations in GSEApy. It handles data loading, preprocessing, and provides internal utilities for enrichment analysis.

Key Responsibilities:

• Data Loading: Supports loading expression data from pandas.DataFrame, pandas.Series, or files (including .gct, .csv, and .rnk formats) via _load_data.
• Data Validation: _check_data handles missing values (filling NAs with 0), duplicate gene IDs (averaging them), and infinite values.
• Gene ID Handling: Includes utilities to check if IDs are Entrez IDs (_is_entrez_id) and to handle case sensitivity (detecting if gene symbols are mostly uppercase).
• Output Management: Manages output directories and logging via prepare_outdir.

Note: This is a base class intended to be subclassed by specific GSEA modules (like gsea, ssgsea, or gsva).

If you see a P-value or FDR of 0 instead of a very small number, it is because the observed Enrichment Score (ES) falls outside the null distribution generated by the random permutation procedure (e.g., 1000 permutations).

To resolve this, you can:

1. Set the smallest possible p-value to 1 / (number of permutations).
2. Increase the number of permutations (this will increase computation time).

Ensure your gene identifiers match the requirements of your chosen input:

• Enrichr library: If using gene_sets from the Enrichr library, gene symbols must be in UPPER CASE.
• Custom GMT files: The gene identifiers in your input gene list must match the identifier type used in your custom GMT file.

Note on non-human organisms: Since GSEApy cannot change the Enrichr databases, if you are working with mouse, fly, fish, or worm data, you should convert your gene symbols to UPPER CASE before running the analysis.