pydeseq2

PyDESeq2 - DESeq2 Differential Expression Analysis in Python

Skill Overview

PyDESeq2 is the Python implementation of DESeq2, designed specifically for differential expression analysis of bulk RNA-seq data. It supports an end-to-end workflow from data loading to result visualization, including multi-factor experimental design, Wald statistical testing, FDR multiple-testing correction, and LFC shrinkage estimation.

Use Cases

1. Transcriptome Differential Expression Analysis

When you need to compare gene expression differences across different experimental conditions—for example, analyzing gene expression changes between treatment and control groups, or between disease and healthy groups. It supports standard two-sample comparisons as well as complex designs such as multi-group treatments and time series.

2. Batch Effect Correction and Multi-factor Design

Suitable for RNA-seq analyses with technical variability (e.g., sequencing batches, library preparation dates) or when multiple biological factors must be considered simultaneously (e.g., age, sex). By using design formulas, you can control covariate effects to obtain more accurate estimates of condition effects.

3. Migrating from R Workflows to Python

Ideal for users who want to move existing R/DESeq2 analysis workflows to the Python ecosystem, or for scenarios where differential expression analysis needs to be integrated into Python data-processing pipelines. Seamlessly compatible with Python data formats such as pandas and AnnData.

Core Features

1. Full DESeq2 Analysis Pipeline

Implements the entire workflow, including data normalization (size factors), dispersion estimation, trend fitting, MAP shrinkage, and log2 fold change calculation. Supports low-count gene filtering, outlier detection (Cook’s distance), and automatic refitting to ensure result reliability.

2. Flexible Experimental Design Support

Supports single-factor and multi-factor design formulas (R/Wilkinson notation), allowing inclusion of categorical variables, continuous variables, and their interaction terms. The order of variables in the design formula determines the order of statistical testing, enabling precise control of covariate adjustment strategy to handle complex experimental designs.

3. Statistical Testing and Result Visualization

Provides Wald testing and independent filtering, supports Benjamini-Hochberg FDR correction, and outputs result tables containing complete statistics such as log2FoldChange, pvalue, and padj. Optionally uses apeGLM LFC shrinkage to improve visualization quality, and supports generating volcano plots and MA plots.

Frequently Asked Questions

What are the differences between PyDESeq2 and the R version of DESeq2?

PyDESeq2 is a Python re-implementation of DESeq2. The core algorithms and statistical methods are the same as the R version, but the API and usage style follow the Python ecosystem. The main differences are: PyDESeq2 0.5.x requires explicitly specifying the contrast parameter and no longer supports default contrasts; it uses pandas DataFrame for data input instead of R’s data.frame; and saving results is recommended in H5AD format rather than RDS. For users with existing R/DESeq2 code, you need to adjust the way you write design formulas and contrast parameters.

How do I handle batch effects in RNA-seq data?

Place the batch variable before the condition variable in the design formula—for example, ~batch + condition. This makes the model estimate batch effects first and then estimate condition effects. If batch and condition are completely confounded (all treatment samples are in the same batch), the design matrix will be rank-deficient, requiring simplification of the design or adding an interaction term ~batch + condition + batch:condition. Before analysis, it’s recommended to check confounding using pd.crosstab(metadata.condition, metadata.batch).

How many samples are needed for differential expression analysis?

The required sample size depends on effect size and biological variability. In general, at least 3 biological replicates per condition is the minimum requirement, and 6 or more is recommended to obtain sufficient statistical power. PyDESeq2 will automatically adjust statistical testing based on data dispersion, but overly small sample sizes can lead to insufficient detection power, making it difficult to find genes with moderately sized effects. If you expect small effects, consider increasing sample size rather than relying only on statistical methods.