📚 课程目录第1章验证方法论概述

一、验证方法论概述

1.1 为什么生信 Pipeline 需要验证

先聊聊这个问题——生信 Pipeline 到底要不要做验证？

我见过不少团队，写了个流程就跑数据，结果出来看着差不多就交差了。直到有一天，某个样本的比对率突然低了 5%，上游工具版本悄悄升级了，参数默认值变了。谁能想到，一个 --min-quality 从 20 改到 25，就能让下游的突变检出量大跳水？

说白了，Pipeline 不是写一次就完事的。它是个活的系统。

我个人习惯把生信 Pipeline 分成三种场景来看：

场景一：工具版本没锁——系统里装的是 v1.2，你开发时用的是 v1.0。两个月后重跑，结果不一样了。
场景二：输入数据「脏」——FASTQ 文件里混了接头序列，BAM 的染色体重命名不一致。Pipeline 不做校验，后期全是坑。
场景三：参数被遗忘——某个命令行参数写在 README 里，新同事没看到，用了默认值跑完全程。

我在项目里遇到过最典型的案例：一个 RNA-seq 定量流程，因为上游 STAR 的 --outFilterMultimapNmax 默认值从 10 改到了 20，某个基因的 FPKM 直接翻了一倍。如果没有验证环节，你根本不知道这是生物学信号，还是工具变化带来的假象。

⚠️ 我曾经… 在部署某临床 WES 流程时，因为依赖的 samtools 从 1.9 升级到 1.11，默认的 CIGAR 处理逻辑微调，导致部分区域覆盖度计算偏差。那之后，我强制要求每次环境变更都必须跑验证集。

1.2 验证与测试的区别

很多人把验证和测试混着用。咱们得掰扯清楚。

你想想看，测试是干嘛的？测试是在问：「我写的代码有没有 bug？」 比如单元测试、集成测试，检查函数返回值对不对，模块间接口通不通。

验证呢？验证在问：「我的 Pipeline 做的是对的吗？」 换句话说，你跑出来的基因表达谱，和真实生物学情况一致吗？你检出的突变，在金标准样本里确实存在吗？

用一个表格来区分，会更直观：

维度	测试 (Testing)	验证 (Validation)
核心问题	代码是否正确实现？	结果是否符合生物学预期？
输入	模拟数据、固定输入	真实样本、金标准数据
输出	通过/失败、覆盖率	准确率、召回率、F1 分数
执行频率	每次代码变更	每次环境/版本/参数变更
我的经验	写单元测试时我会跑 `pytest` 检查函数逻辑	换工具版本前，我会用 MAQC 参考样本跑一遍全流程

嗯，这里要注意：测试不是验证的替代品。你单元测试全过了，不代表 Pipeline 在真实测序数据上能给对结果。反过来，验证通过也不代表代码没 bug。

  一句话总结： 测试保证「代码正确」，验证保证「结果可信」。两者缺一不可。

1.3 验证的生命周期

验证不是一锤子买卖。它贯穿 Pipeline 的整个生命周期，从设计阶段到退役，每一步都有它该做的事。

这张图里的四个阶段，我一个个讲清楚：

阶段一：需求与设计验证

这阶段通常在 Pipeline 还没写代码的时候。你在问：这个 Pipeline 到底要解决什么问题？用哪些工具？预期的准确率是多少？

我习惯在这步做几件事：

拉上生信分析员和实验员，确认分析需求（例如：比对率 ≥ 90%）
选好每个步骤的工具版本，锁死
准备一套金标准参考样本（比如 MAQC / SEQC 系列）

阶段二：实施验证

代码写完了，但还没上生产环境。这时候跑的是小规模样本集，查看每个步骤的输出是不是合理的。

💡 我的习惯： 我会在每个步骤后插入一个简单的检查——比对环节结束后，用 samtools flagstat 看一眼比对率是否在预期范围内。如果比对率只有 30%，大概率是参数或参考基因组配错了。

# 示例：比对后快速验证
samtools flagstat sample.sorted.bam > flagstat.txt
# 检查 mapped rate，预期应 > 85%
grep "mapped" flagstat.txt | head -1

阶段三：部署验证

Pipeline 要进入生产环境，或者要在新集群上部署。这时候要做的是：环境一致性检查 + 回归验证。

我会写一个自动化的部署验证脚本，检查依赖工具版本、计算资源、存储路径等。然后跑一遍验证集，把结果和之前的标准输出做比对。

# 部署验证脚本片段
check_tool_version() {
    local tool=$1
    local required=$2
    local actual=$($tool --version 2>&1 | head -1)
    if [[ "$actual" == *"$required"* ]]; then
        echo "[PASS] $tool version $required"
    else
        echo "[FAIL] $tool expected $required, got $actual"
    fi
}

check_tool_version "bcftools" "1.16"
check_tool_version "guppy_basecaller" "6.4.2"

  🔑 关键原则： 部署验证必须可重复、可自动化。我曾经手动验证了一个小时，结果漏掉了 R 包版本不一致的问题。后来我彻底改用自动化脚本，绝对不会再犯。

阶段四：运维与持续验证

Pipeline 跑起来只是开始。工具更新了怎么办？参考基因组版本变了怎么办？新一批样本的数据质量下降了怎么办？

我记得有一次，某第三方工具升级了小版本号，文档里只写了「bug fixes and minor improvements」，结果它对多比对读段的处理逻辑变了——

我的做法：建立一个「变更触发重新验证」的机制。

工具版本变更 → 自动触发完整验证套件
样本批次质量波动 → 执行质量验证子集
每次运行结束后 → 记录关键指标到验证日志

# 版本变更记录示例
2025-01-15 | bwa 0.7.17 -> 0.7.18 | 验证集通过 | 比对率 +0.2%
2025-03-20 | samtools 1.17 -> 1.18 | 验证集通过 | 无显著差异
2025-05-10 | GATK 4.3.0.0 -> 4.4.0.0 | 验证集失败 | 2个位点测深差异＞5%

⚠️ 避坑提醒： 我曾经以为换一个工具版本只需要跑一个测试样本。结果那次换的是 STAR 的 spliced alignment 算法，一个样本的基因计数变化不明显，但换了三个不同组织类型的样本后，差异就很显著了。所以，验证集一定要覆盖多样本类型和多样本数量。

最后一句话：验证不是一次性的任务，它是 Pipeline 健康的保证书。你越早把验证机制嵌入到开发流程中，后面踩的坑就越少。