McGSEA: Multi-condition Gene Set Enrichment Analysis

McGSEA extends R's popular fast Gene Set Enrichment Analysis (FGSEA) to handle multi-condition experiments. It includes most of the funtionality provided by FGSEA in native python along with its high-performance C++ backend based for multilevel p-value calculation.

TODO [Paper link to be added]

Features

• Python native FGSEA: Python native implementation of R's popular FGSEA package
• Multi-condition analysis: Analyze gene expression across multiple conditions (e.g., drug concentrations, time points)
• Type-safe: Built with pydantic models and pandera schemas for data validation

System Requirements

The package includes a C++ extension that requires compilation during installation.

Python

• Python 3.12 or later

C++ Build Dependencies

You must install these system dependencies before installing mcgsea:

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y build-essential g++ libboost-math-dev cmake

Fedora/RHEL/CentOS

sudo dnf install -y gcc-c++ boost-devel cmake

macOS

brew install boost cmake

Windows

Install Visual Studio Build Tools with C++ support, then install Boost via vcpkg or pre-built binaries.

Installation

From PyPI

pip install mcgsea

From Source

git clone https://github.com/transcriptabio/mcgsea.git
cd mcgsea
pip install -e .

Quick Start

importpandasaspdfrommcgseaimportMcGSEA, load_gene_set_collections# Prepare gene expression data with multi-index: (gene, condition)df=pd.DataFrame({
'gene': ['A', 'A', 'B', 'B', 'C', 'C'],
'concentration': [1, 2, 1, 2, 1, 2],
'log_fold_change': [1.2, 2.1, 0.8, 1.5, -0.5, -1.2]
})
df=df.set_index(['gene', 'concentration'])
# Or convert AnnData to McGSEA formatdf=mcgsea.anndata_to_outcomes(
adata,
entity_index_name='gene', # column in adata.var, or 'var_names'obs_conditions=['concentration'], # condition columns in adata.obs
)
# Load gene set collections (e.g., from GMT files)gene_sets=load_gene_set_collections(['pathway.gmt'])
# Run McGSEAmcgsea=McGSEA(
outcomes=df,
entity_index_name='gene',
entity_sets=gene_sets
)
results=mcgsea.run()
# Results contain enrichment scores, p-values, and adjusted p-valuesprint(results)

Development

Setup

# Clone and install with dev dependencies
git clone https://github.com/transcriptabio/mcgsea.git
cd mcgsea
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Commands

make lint # Run linting checks
make format # Format code
make test# Run tests
make check # Run all checks (lint + test)

Code Style

This project uses Ruff for linting and formatting with Google Python style conventions:

• 80 character line length
• 2-space indentation
• Single quotes for strings

Run make format before submitting PRs.

Building and Publishing

Build Distributions

pip install build
python -m build

This creates both source distribution and wheel in the dist/ directory.

Publish to PyPI

pip install twine
twine upload dist/*

Testing

# Run all tests
pytest src/mcgsea/
# Run with coverage
pytest --cov=src/mcgsea src/mcgsea/

License

MIT License - see LICENSE for details.

The C++ implementation is adapted from fgsea by Alexey Sergushichev, also under MIT license.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run make check to ensure tests pass and code is formatted
4. Submit a pull request

Citation

If you use McGSEA in your research, please cite:

TODO [Citation information to be added]

Authors

• Drishti Guin
• Clayton Mellina

Developed at Transcripta Bio.