alterlab-pydeseq2

PyDESeq2

概述

PyDESeq2 是用 Python 实现的 DESeq2，用于对 bulk RNA-seq 数据进行差异表达分析。它支持从数据加载到结果解读的完整工作流，包括单因素和多因素设计、带多重检验校正的 Wald 检验、可选的 apeGLM 收缩，以及与 pandas 和 AnnData 的集成。

何时使用此技能

在以下情况下使用此技能：

• 分析 bulk RNA-seq 计数数据，进行差异表达分析
• 比较不同实验条件下的基因表达（例如，处理组与对照组）
• 执行考虑批次效应或协变量的多因素设计
• 将基于 R 的 DESeq2 工作流转换为 Python
• 将差异表达分析集成到基于 Python 的流程中
• 用户提到“DESeq2”“差异表达”“RNA-seq 分析”或“PyDESeq2”

不适用的情况

场景	改用
单细胞差异表达或簇标记基因	alterlab-scanpy（标记基因）或 alterlab-scvi-tools（基于模型的差异表达）
将 FASTQ 转换为计数矩阵（salmon/kallisto/STAR 定量、tximport）	alterlab-rnaseq-quant
对非计数数据进行通用回归 / GLM / 混合模型分析	alterlab-statsmodels
从测序读段中进行体细胞或生殖系变异检测	alterlab-nf-core-sarek
微生物组特征表差异丰度分析	alterlab-qiime2-amplicon

安装和要求

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

系统要求（pydeseq2 0.5.x，当前版本为 0.5.4）： Python ≥3.11；numpy ≥2.0、pandas ≥2.2、 scipy ≥1.12、scikit-learn ≥1.4、anndata ≥0.11、formulaic ≥1.0.2 和 formulaic-contrasts ≥0.2 （用于解析 ~ 设计公式并构建对比向量）、matplotlib ≥3.9。这些依赖会自动安装。

API 说明（0.4+）： 并行处理通过 inference 对象配置，而不是使用单独的 n_cpus= 关键字参数：

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)

核心工作流

1. 准备数据 — 以样本 × 基因的形式加载计数数据（若加载为基因 × 样本，则使用 .T 转置）；过滤低计数基因（例如，总读段数 < 10）；删除元数据缺失的样本。
2. 指定设计 — 使用 Wilkinson 公式（"~condition"、"~batch + condition"）；将调整变量放在关注变量之前。
3. 拟合 — DeseqDataSet(...).deseq2() 运行完整流程（大小因子 → 离散度 → LFC → Cook 异常值）。
4. 检验 — DeseqStats(dds, contrast=[var, test, ref]).summary()；读取 results_df。
5. （可选）收缩 — ds.lfc_shrink() 仅用于可视化和排序；p 值不会收缩。
6. 解读/导出 — 按 padj < 0.05 过滤，绘制火山图/MA 图，并保存为 CSV/pickle。

最简框架：

from pydeseq2.dds import DeseqDataSet
from pydeseq2.ds import DeseqStats

dds = DeseqDataSet(counts=counts_df, metadata=metadata, design="~condition")
dds.deseq2()
ds = DeseqStats(dds, contrast=["condition", "treated", "control"])
ds.summary()
significant = ds.results_df[ds.results_df.padj < 0.05]

命令行脚本

此技能包含一个用于标准分析的完整独立脚本：

python scripts/run_deseq2_analysis.py \
  --counts counts.csv \
  --metadata metadata.csv \
  --design "~batch + condition" \
  --contrast condition treated control \
  --output results/ \
  --min-counts 10 --alpha 0.05 --n-cpus 4 --plots

该脚本负责数据加载/验证、基因和样本过滤、运行完整的 DESeq2 流程、使用可自定义参数进行统计检验、导出结果（CSV、pickle），以及可选绘制火山图/MA 图。对于批量处理多个数据集，请参阅 scripts/run_deseq2_analysis.py。

路由指南

• 运行标准分析（加载 → 拟合 → 检验 → 导出），或使用特定设计（两组、多重比较、批次、协变量） → references/pipeline_steps.md。
• 解读结果、对基因排序、绘制火山图/MA 图或查看质量指标 → references/interpretation_and_plots.md。
• 遇到错误（索引不匹配、计数全为零、“not full rank”、没有显著基因） → 查阅 references/interpretation_and_plots.md 中的故障排除部分。
• 需要准确的类/方法参数或对象属性 → references/api_reference.md。
• 复杂实验设计或深入了解工作流 → references/workflow_guide.md。

重要提醒

1. **数据方向很重要：**计数数据通常以基因 × 样本的形式加载，但需要样本 × 基因的形式——如有需要，使用 .T 转置。
2. **样本筛选：**分析前移除缺少元数据的样本。
3. **基因筛选：**剔除低计数基因（例如，总 reads 数 < 10），以提高检验效能。
4. **设计公式顺序：**将调整变量放在关注变量之前（"~batch + condition"）。
5. **LFC 收缩时机：**在检验后进行收缩，仅用于可视化或排序——p 值保持未收缩状态。
6. **显著性：**使用 padj < 0.05（Benjamini-Hochberg FDR），而不是原始 p 值。
7. 对比格式：[variable, test_level, reference_level]。对于三元素列表无法表示的比较（例如交互项、对多个水平取平均），contrast 也接受一个针对设计矩阵列的原始 numpy 对比向量。
8. **保存中间结果：**将 DeseqDataSet 序列化为 pickle，以免重新运行耗时的拟合。
9. 检验折叠变化是否超过阈值，而不只是检验是否为零：DeseqStats(..., lfc_null=1.0, alt_hypothesis="greaterAbs") 会在模型中检验“|LFC| 是否 > 1？”。这是要求效应量达到一定大小的统计学正确方法——事后筛选 lfc_null=0 的结果，要求 `abs(log2FoldChange)

   1`，无法控制该结论的 FDR。

10. 零值较多或稀疏的计数：DeseqDataSet(..., size_factors_fit_type="poscounts") 使用正计数估计器，而非默认的比值中位数估计器；当没有任何基因在所有样本中都被检测到时，后者会失效。control_genes= 可将大小因子估计范围限制为 spike-in 或管家基因。

参考索引

• references/pipeline_steps.md — 快速入门、包含完整代码的六个工作流步骤（数据准备、设计、拟合、检验、收缩、导出），以及四种常见实验设计。
• references/interpretation_and_plots.md — 显著基因筛选与排序、质量指标、火山图和 MA 图，以及故障排除指南。
• references/api_reference.md — PyDESeq2 类、方法、参数和数据结构的完整文档。
• references/workflow_guide.md — 深入且完整的工作流、数据加载模式、多因子设计和最佳实践。

其他资源

• **官方文档：**https://pydeseq2.readthedocs.io
• **GitHub 仓库：**https://github.com/owkin/PyDESeq2
• **论文：**Muzellec et al. (2023) Bioinformatics，DOI: 10.1093/bioinformatics/btad547
• **原始 DESeq2（R）：**Love et al. (2014) Genome Biology，DOI: 10.1186/s13059-014-0550-8