用途:当用户已有原始计数矩阵或计数生成结果,需要差异表达、对比、QC 图或基因排序表时使用该技能。
必要输入:确认原始计数矩阵路径与样本元数据路径;基因 ID 类型与注释映射需求;生物学条件、重复、批次变量、供体配对、协变量与排除项;确切对比与基线水平;偏好统计框架(DESeq2、edgeR、limma-voom 或实验室标准);输出需求(归一化计数、PCA、样本距离、火山图、热图、排序表、GSEA 就绪列表)。
前置条件:在保留原始计数、每个对比有足够生物学重复、样本元数据行名与计数矩阵列名匹配、批次/协变量选择明确、探索性 PCA/样本距离图未显示明显样本交换或失败文库之前,不要开始差异表达。
执行路径:多数计数矩阵用 DESeq2 或 edgeR;研究设计或实验室标准支持时用 limma-voom;使用 Bioconductor 时保持在 R 中,除非用户明确要求纯 Python 流程。
本地运行器:
python plugins/ngs-analysis/scripts/run_bulk_rnaseq_de.py
--count-matrix count_matrix.tsv
--sample-metadata sample_metadata.tsv
--contrasts contrasts.tsv
--execute
方法选择:默认 --method auto;auto 在整数型计数且包可用时用 DESeq2,整数型计数回退 edgeR,非整数表达矩阵用 limma_log2。用 --input-mode 声明 raw_counts、normalized_expression 或 log_expression;auto 会推断模式,若因矩阵已变换而跳过归一化会记录警告。
预检命令: python plugins/ngs-analysis/scripts/ngs_preflight.py --pipeline bulk_rnaseq_differential_expression --emit-install-plan
关键决策:始终说明设计公式与对比;建模中的批次校正与可视化去批次分开;不得利用对比的事后知识过滤基因;配对或重复测量设计需显式建模受试者/供体;报告基因需含效应量、不确定性、校正 p 值与过滤状态。
输出:设计公式与对比清单;QC 图(文库大小、检出基因、PCA/样本距离、均值-方差趋势、离群审查);输入模式感知的矩阵导出及建模/对数尺度矩阵;每个对比的差异表达表;因重复不足或混杂而被阻止的对比生成 .not_tested.tsv 存根;自动启动的 localhost Marimo 审查应用记录于 notebooks/marimo_server.json;小 n、混杂设计、失败样本或无法估计批次变量的注意事项;标准运行包络含 run_manifest.json、config.json、validation/、logs/、versions/、visualizations/、notebooks/、artifact_index.json 与 summary.md。
限制:需足够生物学重复;混杂设计或无法估计的批次变量会阻止部分对比;不提供纯 Python 替代(除非用户明确要求);未提及具体定价、平台支持或效果保证。