pydeseq2-differential-expression
Bulk RNA-seq DE with PyDESeq2: load counts, normalize, fit negative binomial models, Wald test (BH-FDR), LFC shrinkage, volcano/MA plots. Use for two-group comparisons, multi-factor designs with batch correction, multiple contrasts.
Install / Use
npx skills add jaechang-hits/SciAgent-Skills --skill pydeseq2-differential-expressionInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Project & Program ManagementSupported Platforms
Our assessment of pydeseq2-differential-expression
pydeseq2-differential-expression scores 91/100 on our quality scale, 15th of 82 Project & Program Management skills we index (top 19%).
Its SKILL.md is 15 KB long, well organised into 46 sections with 14 code examples: a thorough specification that gives an agent plenty to work with.
It has 367 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 3 months ago, so pydeseq2-differential-expression is actively maintained.
- Our last check on 2026-11-20 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-05. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
pydeseq2-differential-expression compared with similar skills
All 4 of these similar skills score higher than pydeseq2-differential-expression; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| pydeseq2-differential-expression (this skill)by jaechang-hits | 91 | 367 | 3mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 118.9k | 11d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 113.3k | 12d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 80.2k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 40.2k | 10d ago | CLAUDE.md |
Frequently asked questions
- How do I install pydeseq2-differential-expression?
- Run
npx skills add jaechang-hits/SciAgent-Skills --skill pydeseq2-differential-expression. The install tabs above show the steps for each supported agent. - Which AI agents does pydeseq2-differential-expression work with?
- It is written for Zed, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is pydeseq2-differential-expression safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is pydeseq2-differential-expression still maintained?
- The repository was last updated about 3 months ago, so pydeseq2-differential-expression is actively maintained.
Skill content
View source on GitHubname: "pydeseq2-differential-expression" description: "Bulk RNA-seq DE with PyDESeq2: load counts, normalize, fit negative binomial models, Wald test (BH-FDR), LFC shrinkage, volcano/MA plots. Use for two-group comparisons, multi-factor designs with batch correction, multiple contrasts." license: "CC-BY-4.0"
PyDESeq2 Differential Expression Analysis
Overview
PyDESeq2 is a Python reimplementation of the R DESeq2 package for differential gene expression analysis from bulk RNA-seq count data. It fits negative binomial generalized linear models per gene, estimates dispersion with empirical Bayes shrinkage, and performs Wald tests with Benjamini-Hochberg FDR correction. This skill covers the full pipeline from raw counts to publication-ready result tables and visualizations.
When to Use
- Identifying differentially expressed genes between two or more experimental conditions from bulk RNA-seq
- Performing two-group comparisons (e.g., treated vs control) with proper statistical testing
- Running multi-factor designs that account for batch effects or covariates (e.g.,
~batch + condition) - Applying log2 fold change shrinkage (apeGLM) for ranking and visualization
- Use
omics-plottingSKILL after DE for publication-quality plots of differential expression results - Converting R-based DESeq2 workflows to a pure Python environment
- Integrating DE analysis into larger Python bioinformatics pipelines (e.g., with scanpy, pandas)
- Use DESeq2 (R/Bioconductor) or edgeR instead for the reference R implementations with the broadest method support and community validation
Prerequisites
- Python packages:
pydeseq2>=0.4,pandas>=1.4,numpy>=1.23,scipy>=1.11,scikit-learn>=1.1,anndata>=0.8 - Data requirements: Raw (unnormalized) integer count matrix (samples x genes) + sample metadata DataFrame
- Environment: Python 3.10+; optional
matplotlib,seabornfor visualization
pip install pydeseq2 matplotlib seaborn
Pre-flight Interview
Settle these with the user before writing any analysis code.
decisions:
- id: D1
param: design
kind: required
source: data
ask: "Which column of the sample sheet separates the groups you want to compare?"
default: null
- id: D2
param: contrast
kind: required
source: user
depends_on: [D1]
ask: "Within that column, which group is the baseline the others are measured against?"
default: null
- id: D3
param: design
kind: required
source: data
depends_on: [D1]
ask: "Is there a nuisance variable to adjust for (batch, donor, sex, sequencing run)?"
default: "none - compare groups without covariates"
skip_if: "sample sheet carries no column besides the grouping variable"
- id: D4
param: alpha
kind: optional
source: user
ask: "How strong must the evidence be before a gene counts as changed (false-discovery rate)?"
default: 0.05
- id: D5
param: lfc_cutoff
kind: optional
source: user
ask: "How large a fold change is worth reporting, on top of the statistical call?"
default: "|log2FC| > 0.58 (1.5x change)"
- id: D6
param: min_total_counts
kind: optional_conditional
source: data
ask: "Genes with very few reads cannot be tested - where should the floor sit?"
default: 10
- id: D7
param: lfc_shrink
kind: optional
source: user
ask: "Shrink fold-change estimates so low-count genes stop dominating the rankings and plots?"
default: "applied for ranking and visualization, not for significance calls"
- id: D8
param: refit_cooks, cooks_filter, independent_filter
kind: optional
source: user
ask: "Should DESeq2 retain its default outlier replacement and adaptive filtering behavior?"
default: true
- id: D9
param: n_cpus
kind: never_ask
source: data
reason: "Affects runtime only, not the result"
default: 4
design appears twice because the formula is assembled from both D1 and D3;
D2 then selects which coefficient of that fitted model is tested.
Workflow
Step 1: Data Loading and Validation
Load the count matrix and metadata. PyDESeq2 expects counts as a samples x genes DataFrame with non-negative integers, and metadata as a samples x variables DataFrame with matching indices.
import pandas as pd
# Load data — typical CSV has genes as rows, samples as columns
counts_raw = pd.read_csv("counts.csv", index_col=0)
metadata = pd.read_csv("metadata.csv", index_col=0)
# Transpose if needed: PyDESeq2 requires samples x genes
if counts_raw.shape[0] > counts_raw.shape[1]:
counts_df = counts_raw.T # genes x samples → samples x genes
else:
counts_df = counts_raw
# Validate alignment
common_samples = counts_df.index.intersection(metadata.index)
counts_df = counts_df.loc[common_samples]
metadata = metadata.loc[common_samples]
print(f"Samples: {counts_df.shape[0]}, Genes: {counts_df.shape[1]}")
print(f"Metadata columns: {list(metadata.columns)}")
print(f"Condition counts:\n{metadata['condition'].value_counts()}")
Step 2: Gene Filtering
Remove lowly expressed genes to improve statistical power and reduce multiple testing burden.
# Filter genes with total counts below threshold
min_total_counts = 10
gene_counts = counts_df.sum(axis=0)
genes_to_keep = gene_counts[gene_counts >= min_total_counts].index
counts_df = counts_df[genes_to_keep]
# Optional: require minimum counts in a minimum number of samples
min_count_per_sample = 5
min_samples = 3
genes_expressed = (counts_df >= min_count_per_sample).sum(axis=0) >= min_samples
counts_df = counts_df.loc[:, genes_expressed]
print(f"Genes after filtering: {counts_df.shape[1]}")
Step 3: DeseqDataSet Initialization and Fitting
Create the DESeq dataset object, specify the design formula, and run the full pipeline (size factor estimation, dispersion estimation, model fitting).
from pydeseq2.dds import DeseqDataSet
dds = DeseqDataSet(
counts=counts_df,
metadata=metadata,
design="~condition", # Wilkinson-style formula
refit_cooks=True, # Refit after Cook's outlier removal
n_cpus=4 # Parallel threads
)
# Run: size factors → dispersions → trend → MAP shrinkage → LFC fitting
dds.deseq2()
# Inspect normalization
print(f"Size factors (first 5): {dds.obsm['size_factors'][:5]}")
print(f"Size factor range: {dds.obsm['size_factors'].min():.2f} - {dds.obsm['size_factors'].max():.2f}")
Step 4: Statistical Testing (Wald Test)
Perform Wald tests to identify differentially expressed genes. Specify the contrast as [variable, test_level, reference_level].
from pydeseq2.ds import DeseqStats
ds = DeseqStats(
dds,
contrast=["condition", "treated", "control"],
alpha=0.05, # FDR threshold
cooks_filter=True, # Filter Cook's outliers
independent_filter=True # Independent filtering for power
)
ds.summary()
# Access full results
results = ds.results_df
print(f"Total genes tested: {len(results)}")
print(f"Significant (padj < 0.05): {(results.padj < 0.05).sum()}")
Step 5: LFC Shrinkage (Optional)
Apply apeGLM shrinkage to reduce noise in log2 fold change estimates. Use shrunk values for visualization and ranking, not for significance calls.
# Apply shrinkage — modifies results_df.log2FoldChange in place
ds.lfc_shrink()
# Compare pre/post shrinkage effect
print(f"Max |LFC| after shrinkage: {results.log2FoldChange.abs().max():.2f}")
print(f"Genes with |LFC| > 2: {(results.log2FoldChange.abs() > 2).sum()}")
Step 6: Result Filtering and Export
Filter significant genes and export results for downstream analysis.
import numpy as np
# Significance + effect size filter
significant = results[
(results.padj < 0.05) &
(results.log2FoldChange.abs() > 1.0)
].copy()
# Separate up/down-regulated
up = significant[significant.log2FoldChange > 0].sort_values("padj")
down = significant[significant.log2FoldChange < 0].sort_values("padj")
print(f"Upregulated: {len(up)}, Downregulated: {len(down)}")
# Export
results.to_csv("deseq2_all_results.csv")
significant.to_csv("deseq2_significant.csv")
up.to_csv("deseq2_upregulated.csv")
down.to_csv("deseq2_downregulated.csv")
print("Results exported to CSV files")
Step 7: Visualization — Volcano Plot
Prepare the DEG table, then read skills/data-visualization/omics-plotting/SKILL.md and follow its "Volcano" recipe on the exported CSV (→ figures/volcano_plot.png).
# Volcano input = log2FoldChange vs padj; saved in Step 6 as deseq2_all_results.csv
volcano_input = results[["log2FoldChange", "padj"]].dropna()
print(f"Volcano input: {len(volcano_input)} genes -> deseq2_all_results.csv")
# Render with the omics-plotting SKILL (`skills/data-visualization/omics-plotting/SKILL.md`) "Volcano" recipe.
Step 8: Visualization — MA Plot
Prepare the DEG table, then read skills/data-visualization/omics-plotting/SKILL.md and follow its "MA plot" recipe on the exported CSV (→ figures/ma_plot.png).
# MA input = log2FoldChange vs mean normalized count (baseMean); from deseq2_all_results.csv
ma_input = results[["baseMean", "log2FoldChange", "padj"]].dropna(subset=["padj"])
print(f"MA input: {len(ma_input)} genes -> deseq2_all_results.csv")
# Render with the omics-plotting SKILL (`skills/data-visualization/omics-plotting/SKILL.md`) "MA plot" recipe.
Key Parameters
| Parameter | Default | Range / Options | Effect |
|-----------|---------|-----------------|--------|
| design | (required) | Wilkinson formula | Model formula; put covariates before variable of interest |
| contrast | None | [var, test, ref] | Which comparison to test; None uses last coefficient |
| alpha | 0.05 | 0.01–0.10 | FDR threshold for significance calling |
| refit_cooks | True | True/False | Refit model after removing Cook's distance outliers |
| cooks_filter | True | True/False | Apply Cook's distance filtering during testing |
| independent_filter | True | True/False | Independent filtering to optimize detection power |
| n_cpus | 1 | 1–N | Number of parallel threads for dispersion fitting |
| min_total_counts (user) | 10 | 5–50 | Gene filtering: minimum total reads across all samples |
| lfc_shrink() | off | call after summary() | apeGLM shrinkage; reduces noisy LFC estimates |
Common Recipes
Recipe: Multiple Contrasts from One Model
When comparing multiple treatment groups against a shared control.
dds = DeseqDataSet(counts=counts_df, metadata=metadata, design="~condition")
dds.deseq2()
contrasts = {
"A_vs_ctrl": ["condition", "treatment_A", "control"],
"B_vs_ctrl": ["condition", "treatment_B", "control"],
"C_vs_ctrl": ["condition", "treatment_C", "control"],
}
for name, contrast in contrasts.items():
ds = DeseqStats(dds, contrast=contrast, alpha=0.05)
ds.summary()
n_sig = (ds.results_df.padj < 0.05).sum()
ds.results_df.to_csv(f"results_{name}.csv")
print(f"{name}: {n_sig} significant genes")
Recipe: Batch-Corrected Analysis
When samples come from multiple batches or sequencing runs.
# Verify batch is not confounded with condition
print(pd.crosstab(metadata["batch"], metadata["condition"]))
dds = DeseqDataSet(
counts=counts_df, metadata=metadata,
design="~batch + condition" # batch first, then variable of interest
)
dds.deseq2()
ds = DeseqStats(dds, contrast=["condition", "treated", "control"])
ds.summary()
print(f"Significant genes (batch-corrected): {(ds.results_df.padj < 0.05).sum()}")
Recipe: P-value Distribution QC
Diagnostic check — a healthy analysis shows a flat histogram with a spike near 0.
import matplotlib.pyplot as plt
fig, axes = plt.subplots(1, 2, figsize=(12, 5))
# P-value histogram
axes[0].hist(ds.results_df.pvalue.dropna(), bins=
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
118.9kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
113.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
80.2kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Claude-Code-Game-Studios
40.2kTurn Claude Code into a full game dev studio — 49 AI agents, 75 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
