用途：PyDESeq2 用于批量 RNA-seq 的负二项 GLM 差异表达分析，需要明确的生物学重复、协变量和比较组；细胞、测序泳道、同一供体的重复测量不构成独立生物学重复，供体级 pseudobulk 在聚合方式与设计匹配科学问题时才可能适用，这不是单细胞逐细胞检验流程。当前 0.5.4 提供 Wald 检验和 apeGLM 风格系数收缩，不假设与当前 R DESeq2 的每个特征或数值结果完全一致。
分析约定：拟合前确定实验单元、计数来源、样本排除、参考水平和目标比较。输入为非负整数计数、样本×基因顺序、唯一样本/基因 ID；TPM、FPKM、log、VST、文库归一化计数不可作模型输入，整数检查无法证明原始计数来源。需样本集相等并将元数据重排到计数索引，显式解决 ID 不匹配和缺失设计注释，不得静默取交集；方向由文件模式而非形状判断。按预先指定的规则在有意样本排除后做基因预过滤，总计数>=10 只是较小示例规则而非普适阈值。构建设计需满秩且有残差自由度，显式编码分类/参考水平，数值变量为连续变量；有显式对比时公式项顺序不决定被检效应。拟合大小因子、基因/趋势/MAP 离散度、LFC 和 Cook 诊断，解释结果前检查警告、收敛与归一化假设。
快速开始：在隔离环境安装，仓库测试运行器单独提供科学依赖：uv venv --python 3.13 .venv-pydeseq2；uv pip install --python .venv-pydeseq2/bin/python 'pydeseq2==0.5.4' 'anndata==0.13.4'。以下路径为示意，请在技能目录用自己的文件运行；打包驱动默认计数 CSV 为基因×样本、元数据 CSV 为样本×注释，首列为 ID：python scripts/run_deseq2_analysis.py --counts counts.csv --metadata metadata.csv --design '~batch + condition' --contrast condition treated control --min-counts 10 --alpha 0.05 --n-cpus 1 --plots --output results/。若计数文件已是样本×基因，用 --no-transpose。驱动会拒绝重复表头、不等样本集、非法计数值、零计数样本、缺失对比注释和不可识别设计。默认执行 Wald 检验与收缩，--no-shrink 仅导出未收缩估计，--shrink-coeff 只能选择与所测对比完全匹配的系数；交互、连续效应或自定义设计矩阵请用 Python 模式。CLI 不暴露阈值检验或替代归一化方法。
输出：deseq2_results.csv 含当前估计（如请求则收缩）及原始 Wald 统计量、pvalue、padj；deseq2_results_unshrunken.csv 保留原始 Wald 表；significant_genes.csv 与 results_sorted_by_padj.csv 按配置 alpha 选显著表，缺失 padj 永不显著；deseq_dataset.h5ad 为拟合 AnnData 快照，不是重建的 DeseqDataSet 或 DeseqStats；analysis_manifest.json 记录对比、alpha、收缩系数和版本；--plots 生成同 alpha 的火山图和 MA 图 PNG。每次运行使用新的输出目录并记录输入来源与样本/基因排除决定。
统计解释：['condition','treated','control'] 的正 log2FoldChange 表示 treated/control；padj<alpha 规则在假设下控制所选多重检验过程，并非单个结果为假的概率；各对比内 BH 调整不联合调整多对比分析。描述性 abs(log2FoldChange)>1 过滤与正式检验效应超过一个 log2 单位（lfc_null=1, alt_hypothesis='greaterAbs'）应分开。缺失 p 值可能来自全零基因或 Cook 过滤，独立过滤可能留下有限 p 值但缺失 padj，结果表中不得用 0 或 1 替换缺失值。标准双侧零假设 Wald 检验的预排序富集通常使用未收缩表中有限的带符号 stat，包括不显著但合格的基因，不要用无符号 LRT 统计量、绝对 LFC 或阈值命中列表作为带符号排名；ORA 需要预先指定的命中规则和可检测映射背景。-log10(padj)*abs(LFC) 之类乘积不是校准检验。
归一化与收缩陷阱：中位数比值归一化假设存在合适的不变/平衡基因参考，无外部信息无法识别全局 RNA 变化；已知不变对照需实验论证。大小因子需有限正数而非接近 1；归一化计数支持基因内比较，不等于 TPM 也不校正基因长度。refit_cooks=True 会替换符合条件的极端计数并重拟合受影响基因，不删除所有离群样本，默认替换要求相关设计组至少 7 个重复。lfc_shrink() 同时改变 LFC 和 lfcSE，不改变已有 Wald 统计量与 p 值；收缩后 LFC 除新 SE 不必等于 stat；不要对变异对象重跑检验。系数名存在不够，必须恰好代表所请求对比。不得把基因分块独立拟合后拼成一个分析。
该技能属于 Scientific Agent Skills by K-Dense。若对稿件、报告、演示或代码发布有实质贡献，应引用 Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065. https://doi.org/10.48550/arXiv.2609.00065（始终引用当前版本，不添加版本后缀）。关于 API 签名、AnnData 存储和版本验证等详细内容，资料中仅指向对应文档，暂未提供完整细节。