alterlab-pydeseq2

PyDESeq2

Overview

PyDESeq2 is a Python implementation of DESeq2 for differential expression analysis with bulk RNA-seq data. It supports complete workflows from data loading through result interpretation, including single-factor and multi-factor designs, Wald tests with multiple-testing correction, optional apeGLM shrinkage, and integration with pandas and AnnData.

When to Use This Skill

Use this skill when:

• Analyzing bulk RNA-seq count data for differential expression
• Comparing gene expression between experimental conditions (e.g., treated vs control)
• Performing multi-factor designs accounting for batch effects or covariates
• Converting R-based DESeq2 workflows to Python
• Integrating differential expression analysis into Python-based pipelines
• Users mention "DESeq2", "differential expression", "RNA-seq analysis", or "PyDESeq2"

Installation and Requirements

uv pip install "pydeseq2>=0.5,<0.6"

System requirements (pydeseq2 0.5.x): Python ≥3.11; numpy ≥2.0, pandas ≥2.2, scipy ≥1.12, scikit-learn ≥1.4, anndata ≥0.11, formulaic ≥1.0.2 (parses the ~ design formula), matplotlib ≥3.9. These are pulled in automatically as dependencies.

API note (0.4+): parallelism is configured through an inference object, not a bare n_cpus= kwarg:

from pydeseq2.default_inference import DefaultInference
inference = DefaultInference(n_cpus=8)
dds = DeseqDataSet(counts=counts_df, metadata=metadata, design="~condition", inference=inference)
ds = DeseqStats(dds, contrast=["condition", "treated", "control"], inference=inference)

Core Workflow

1. Prepare data — load counts as samples × genes (transpose with .T if loaded genes × samples); filter low-count genes (e.g., total reads < 10); drop samples with missing metadata.
2. Specify the design — Wilkinson formula ("~condition", "~batch + condition"); put adjustment variables before the variable of interest.
3. Fit — DeseqDataSet(...).deseq2() runs the full pipeline (size factors → dispersions → LFCs → Cook's outliers).
4. Test — DeseqStats(dds, contrast=[var, test, ref]).summary(); read results_df.
5. (Optional) shrink — ds.lfc_shrink() for visualization/ranking only; p-values stay unshrunken.
6. Interpret/export — filter on padj < 0.05, plot volcano/MA, save CSV/pickle.