Registry / data / pydeseq2

pydeseq2

JSON →
library0.5.4pypypi✓ verified 25d ago

PyDESeq2 is a Python implementation of the DESeq2 method for differential expression analysis (DEA) with bulk RNA-seq data. It enables researchers to perform single-factor and multi-factor designs, Wald tests with multiple testing correction, and optional LFC shrinkage. The library is actively maintained, with version 0.5.4 being the latest stable release, and it is part of the scverse ecosystem, integrating with AnnData for data handling.

pip install pydeseq2
INSTALL
IMPORT
SIG · PYDESEQ2
P
pydeseq2
datapythonv0.5.4
Install
20.8s avg
Import
6650ms
Disk
496MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
build_error
glibc
py 3.103.95 runs
installs and imports cleanly · install 20.8s · import 6.650s · 451MB
496MB installed
● package 496MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

DeseqDataSet
from pydeseq2.dds import DeseqDataSet
DeseqStats
from pydeseq2.ds import DeseqStats
load_example_data
from pydeseq2.utils import load_example_data
Useful for getting started with built-in example data.

This quickstart demonstrates a typical PyDESeq2 workflow for differential expression analysis. It covers loading data, initializing a `DeseqDataSet` with a `formulaic` design string, running the DESeq2 pipeline, performing Wald tests, and applying LFC shrinkage. Results are accessible via the `DeseqStats` object's `results_df` attribute.

import pandas as pd from pydeseq2.dds import DeseqDataSet from pydeseq2.ds import DeseqStats # 1. Create dummy count data (genes x samples) and metadata # In a real scenario, load with pd.read_csv('counts.csv', index_col=0).T # and pd.read_csv('metadata.csv', index_col=0) counts_df = pd.DataFrame( { 'sample1': [100, 50, 200, 10, 5, 150], 'sample2': [120, 60, 210, 12, 6, 160], 'sample3': [10, 5, 20, 100, 50, 15], 'sample4': [15, 7, 25, 110, 55, 18] }, index=['geneA', 'geneB', 'geneC', 'geneD', 'geneE', 'geneF'] ).T # Transpose to samples x genes metadata = pd.DataFrame( { 'condition': ['treated', 'treated', 'control', 'control'], 'batch': ['batch1', 'batch2', 'batch1', 'batch2'] }, index=['sample1', 'sample2', 'sample3', 'sample4'] ) # Ensure counts_df index (samples) matches metadata index (samples) assert counts_df.index.equals(metadata.index) # 2. Filter low-count genes (optional, but good practice) genes_to_keep = counts_df.columns[counts_df.sum(axis=0) >= 10] counts_df = counts_df[genes_to_keep] # 3. Initialize DeseqDataSet with a formulaic design dds = DeseqDataSet( counts=counts_df, metadata=metadata, design='~condition' ) # 4. Run the DESeq2 pipeline (normalization, dispersion, LFC estimation) dds.deseq2() # 5. Perform statistical testing deseq_stats = DeseqStats(dds, contrast=['condition', 'treated', 'control']) deseq_stats.wald_test() # 6. Apply LFC shrinkage (optional) deseq_stats.lfc_shrink(coeff='condition_treated_vs_control') # 7. Access results results = deseq_stats.results_df print(results.head()) # You can also access attributes directly from dds, e.g., normalized counts # print(dds.layers['normed_counts'].head())
Debug
Known issues
breakingPython 3.10 is no longer supported starting from PyDESeq2 v0.5.3.
fix
Upgrade your Python environment to 3.11 or higher.
affects: >=0.5.3
breakingThe `design` argument of `DeseqDataSet` changed in v0.5.0 to accept `formulaic` string formulas (e.g., `'~condition'`) instead of pandas DataFrames for the design matrix directly. Python 3.9 also dropped support.
fix
Update your `DeseqDataSet` initialization to use a `formulaic` string (e.g., `design='~condition + batch'`). Ensure your Python version is >=3.11.
affects: >=0.5.0
gotchaIn v0.5.2, 1D variables stored in `obsm` and `varm` attributes of the AnnData-like `DeseqDataSet` were moved to `obs` and `var` respectively for better consistency with AnnData standards.
fix
If accessing 1D variables, check `dds.obs` or `dds.var` instead of `dds.obsm` or `dds.varm`.
affects: >=0.5.2
gotchaPyDESeq2 v0.5.4 includes fixes for pandas 3 data type and copy/write bugs. Users on older PyDESeq2 versions combined with pandas 3.x might encounter unexpected behavior.
fix
Upgrade PyDESeq2 to v0.5.4 or newer to ensure full compatibility with pandas 3.x.
affects: <0.5.4
gotchaPyDESeq2 is a re-implementation of the R DESeq2 method. While it aims for similar results and features, there might be subtle differences in computed values or available functionalities compared to the original R package.
fix
Consult the PyDESeq2 documentation for specific implementation details and known differences if comparing results with R's DESeq2.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pydeseq2'
The 'pydeseq2' package is not installed in the current Python environment.
fix
Install the package using pip: 'pip install pydeseq2'.
ImportError: cannot import name 'DeseqDataSet' from 'pydeseq2'
The 'DeseqDataSet' class has been moved or renamed in the 'pydeseq2' package.
fix
Update the import statement to: 'from pydeseq2 import DeseqDataSet'.
TypeError: 'design' argument must be a string formula
The 'design' argument in 'DeseqDataSet' now requires a string formula instead of a DataFrame.
fix
Provide the design as a string formula, e.g., 'design="~ condition"'.
ValueError: Python version 3.10 is not supported
PyDESeq2 version 0.5.3 and later require Python 3.11 or higher.
fix
Upgrade your Python environment to version 3.11 or higher.
AttributeError: module 'pydeseq2' has no attribute 'run_deseq'
The function 'run_deseq' has been removed or renamed in the 'pydeseq2' package.
fix
Refer to the latest documentation for the correct function name and usage.
Upgrade
Version history
0.5.4latest on PyPI · released Jan 23, 2026
Audit
Dependencies
anndatarequiredCore data structure for storing count matrices and metadata, part of the scverse ecosystem.
formulaicrequiredUsed for parsing R-style design formulas.
numpyrequiredFundamental package for numerical computing.
pandasrequiredUsed for handling dataframes for counts and metadata.
scipyrequiredProvides scientific computing tools, including generalized linear models.
scikit-learnrequiredMachine learning utilities.
matplotlib-baseoptionalOptional dependency for plotting results.
Agent activity
17 hits · last 30 days
node
14
OpenAI (training)
1
Resources