PyDESeq2 Documentation

PyDESeq2 is a Python implementation of the DESeq2 method for differential expression analysis (DEA) using bulk RNA-seq data. It is designed to facilitate DEA experiments for Python users by providing a native Python interface for workflows originally developed in R.

Key Features:

• Supports single-factor and multi-factor analysis (using categorical or continuous factors).
• Uses Wald tests for differential expression.
• Includes an optional apeGLM LFC (Log Fold Change) shrinkage step.
• Broadly corresponds to the default settings of DESeq2 (v1.34.0).

Note: As this is a re-implementation from scratch, results may differ slightly from the original R implementation in terms of retrieved values or specific feature availability.

PyDESeq2 provides a Python implementation of the DESeq2 differential expression analysis pipeline. The core API is organized into several key modules:

• DeseqDataSet: The primary data container and orchestrator for the DESeq2 workflow.
• DeseqStats: Used for performing statistical tests and calculating differential expression results.
• Inference and DefaultInference: Classes for handling the statistical inference process.
• grid_search: Tools for hyperparameter optimization.
• preprocessing: Utilities for preparing data for analysis.
• utils: General helper functions.

It is recommended to install PyDESeq2 within a dedicated conda environment to manage dependencies effectively.

conda env create -n pydeseq2
conda activate pydeseq2
pip install pydeseq2

Before reporting an issue, check the PyDESeq2 issue tracker to see if it has already been described. If it exists, you can add a 'thumbs up' to help prioritize it.

When reporting a new issue, provide:

• Precise details on how to reproduce the issue (include code snippets if possible).
• A clear description of how a requested feature should function.
• The version of pydeseq2 you are using.

You can check your version using:

import pydeseq2
print(pydeseq2.__version__)

You can install PyDESeq2 using several package managers depending on your environment preference.

Using pip

Install directly from PyPI:

pip install pydeseq2

It is recommended to install within a conda environment to manage dependencies effectively:

conda create -n pydeseq2
conda activate pydeseq2
conda install pip
pip install pydeseq2

Using uv

If you use uv, add it to your project with:

uv add pydeseq2

Using Bioconda

Install via the Bioconda channel using conda:

conda install -c bioconda pydeseq2

You can retrieve example synthetic datasets for testing or demonstration purposes using the load_example_data function from the pydeseq2.utils module. Currently, only synthetic data is available. The provided datasets include test_clinical.csv and test_counts.csv, which were generated to handle multiple factors.

from pydeseq2.utils import load_example_data

# Example usage to load example data
data = load_example_data()

You can install PyDESeq2 directly from PyPI using pip.

pip install pydeseq2

If you are contributing to the documentation, ensure you have installed the dev and doc extras using uv sync --extra dev --extra doc.

To verify your documentation changes locally:

1. Export requirements (if necessary for your environment setup):

   uv pip freeze > requirements.txt

2. Build the HTML documentation:

   cd docs
   make clean html

3. View the result: Open the generated files in docs/build/html to confirm the build is correct.

To build the documentation locally, clone the repository and set up a development environment using uv. After synchronizing dependencies with the dev and doc extras, you can build the HTML documentation using make within the docs directory.

# 1. Clone the repository
git clone https://github.com/owkin/PyDESeq2.git
cd PyDESeq2

# 2. Set up environment with uv
uv venv
source .venv/bin/activate
uv sync --extra dev --extra doc
uv pip freeze > requirements.txt

# 3. Build the documentation
cd docs
make clean html

To contribute code or documentation, follow these steps to set up a local development environment using uv:

1. Fork and Clone: Fork the repository on GitHub and clone your fork locally:

   git clone git@github:<your-github-username>/pydeseq2.git
   cd pydeseq2

2. Create Virtual Environment: Use uv to create a Python 3.13 (or higher) environment:

   uv venv --python 3.13
   source venv/bin/activate

3. Install Dependencies: Install pydeseq2 in development mode along with documentation and development extras:

   uv sync --extra dev --extra doc

   Note: This also installs ruff, isort, and mypy via pre-commit hooks.

4. Configure Upstream: Add the original repository as a remote to keep your fork synchronized:

   git remote add upstream git@github.com:owkin/pydeseq2.git
   git remote -v

Follow this workflow to submit a Pull Request (PR) for code changes:

1. Sync with Upstream: Ensure your local main branch is up to date:

   git checkout main
   git fetch upstream
   git merge upstream/main --rebase

2. Create a Feature Branch:

   git checkout -b my_new_branch

3. Develop and Commit: Make your changes. The pre-commit tool will automatically check for style and type compatibility on every commit.
4. Push and PR: Push your branch to your GitHub fork and create a Pull Request:

   git push -u origin my_feature

Ensure your PR description is detailed enough for reviewers to understand your changes. You must respond to all reviewer comments before the PR can be merged.