企业官网建设流程全解析

nf-core/sarek 3.7.1 变异检测全流程实战：基于 Nextflow 的 WGS/WES Germline 与 Somatic 分析指南

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins

nf-core/sarek 是 nf-core 社区维护的高通量变异检测流程，面向 WGS（全基因组测序）与 WES（全外显子组测序）数据，统一封装了比对、质控、碱基质量值重校准（BQSR）、变异检测与功能注释的完整链路。本指南以当前仓库knowledge-work-plugins中 nextflow-development 技能对 sarek 3.7.1 的工程化封装为主线，结合仓库内的 samplesheet 自动生成脚本、管线配置与校验工具，系统讲解从环境验证、测试运行、样本表构建到变异检测模式选择的完整实战方案。读者完成后将掌握用一条条可复现的 Nextflow 命令完成胚系（germline）与体细胞（somatic）变异分析，并能读懂、排查和分析 Sarek 的核心输出文件。

Sarek 在 nextflow-development 技能中的定位

nextflow-development技能面向缺少专业生信训练的科研人员，目标是让"跑大规模组学分析"这件事变成可交互、可校验的标准化流程。其总体工作流分为六步：获取数据（GEO/SRA）→ 环境检查 → 选择管线 → 测试运行 → 生成 samplesheet → 配置并运行 → 校验输出，完整流程见 SKILL.md。

在管线选择矩阵中，Sarek 3.7.1 被指定用于WGS/WES 变异检测场景：

该定位与 Sarek 管线的配置元数据一致：在 sarek.yaml 中声明了WGS、WES、tumor-normal、germline、somatic等数据类型，并定义了 filename / directory 两级检测线索（如tumor、normal、germline、exome、variant），供 detect_data_type.py 在自动识别数据时使用。

版本锁定提示：本指南所有命令均以 sarek3.7.1为准。升级新版本前务必查阅其 releases 页面确认 breaking changes，并同步更新本文所有命令中的-r版本号，同时更新 sarek.yaml 中的version字段及文档链接。

第一步：测试命令验证环境

任何真实数据运行之前，先跑官方 test profile 验证环境。该命令下载小规模测试数据，验证 Docker/Nextflow/Java 环境与网络连通性：

nextflow run nf-core/sarek -r 3.7.1 -profile test,docker --outdir test_sarek

预期耗时约 20 分钟，产出对齐后的 BAM 与变异调用（VCF）文件。运行结束后按 SKILL.md 的 Step 3 约定完成两项校验：

ls test_sarek/multiqc/multiqc_report.html grep "Pipeline completed successfully" .nextflow.log

sarek.yaml中的test_profile配置同样把test_sarek/multiqc/multiqc_report.html与日志中的Pipeline completed successfully作为成功判定标准。测试失败时，排查思路见 troubleshooting.md：常见退出码 137/143/104/134/139/247 均为内存不足，通过提高--max_memory解决；容器拉取失败可改用-profile singularity或离线方案nf-core download sarek -r 3.7.1。

Samplesheet 格式：Sarek 的三种输入范式

Sarek 支持 FASTQ、BAM、CRAM 三种输入，分别对应从原始测序读段开始或从已有比对结果开始的两类场景。

从 FASTQ 开始

多 lane 测序数据按patient/sample/lane拆行，同一 lane 一对 R1/R2：

patient,sample,lane,fastq_1,fastq_2 patient1,tumor,L001,/path/to/tumor_L001_R1.fq.gz,/path/to/tumor_L001_R2.fq.gz patient1,tumor,L002,/path/to/tumor_L002_R1.fq.gz,/path/to/tumor_L002_R2.fq.gz patient1,normal,L001,/path/to/normal_R1.fq.gz,/path/to/normal_R2.fq.gz

从 BAM/CRAM 开始

已有比对结果时直接提供 BAM 与其索引：

patient,sample,bam,bai patient1,tumor,/path/to/tumor.bam,/path/to/tumor.bam.bai patient1,normal,/path/to/normal.bam,/path/to/normal.bam.bai

带 tumor/normal 状态

status列是体细胞分析的核心：0 = normal，1 = tumor：

patient,sample,lane,fastq_1,fastq_2,status patient1,tumor,L001,tumor_R1.fq.gz,tumor_R2.fq.gz,1 patient1,normal,L001,normal_R1.fq.gz,normal_R2.fq.gz,0

用仓库脚本自动生成与校验 samplesheet

手工编辑多行 CSV 容易出错，仓库提供了基于管线配置驱动的自动生成器 generate_samplesheet.py：

# 从 FASTQ 目录自动生成（自动配对 R1/R2、推断 patient/lane、提示 tumor/normal 状态） python scripts/generate_samplesheet.py /path/to/data sarek -o samplesheet.csv # 从 BAM 目录生成 python scripts/generate_samplesheet.py /path/to/bams sarek --input-type bam # 校验已有 samplesheet python scripts/generate_samplesheet.py --validate samplesheet.csv sarek

该脚本的列定义完全来自 sarek.yaml 的samplesheet.columns配置：patient/sample/fastq_1/fastq_2/bam/bai为必填列，lane默认L001，status仅允许 0/1、默认 0。底层逻辑值得关注：

• R1/R2 配对：sample_inference.py中的 match_read_pairs 使用带优先级的正则评分系统（如_R1_001权重 10、_1.权重 5），按 lane 聚合样本键后再配对；
• tumor/normal 推断：infer_tumor_normal_status 依据tumor/tumour/metastasis/cancer等肿瘤关键词与normal/germline/blood/pbmc/control等正常关键词自动判断状态；无法判断时脚本会交互式询问（0或1），非交互模式默认按 normal 处理；
• 写出前校验：validators.py的 validate_samplesheet 会检查必填列、路径是否存在、枚举值合法性、R1/R2 配对一致性，并对 sarek 执行 _validate_sarek_specific：若某患者只有 tumor 样本而没有 matched normal，会给出"体细胞分析最好配对正常样本"的警告与建议。

所有路径务必使用绝对路径，这是 nf-core 管线的硬性要求，也是"no such file"类报错的最常见来源。

变异检测模式：四种典型运行方式

Sarek 的核心设计是"一个管线、多套工具组合"。按照 sarek.yaml 的decision_points，工具选择由数据是否有 tumor/normal 对决定。

胚系变异（单样本）

正常样本的遗传变异检测，使用 GATK HaplotypeCaller 加 SnpEff 注释：

nextflow run nf-core/sarek -r 3.7.1 -profile docker \ --input samplesheet.csv --outdir results --genome GRCh38 \ --tools haplotypecaller,snpeff

体细胞变异（tumor-normal 配对）

肿瘤样本需匹配正常样本以过滤胚系污染，使用 Mutect2 与 Strelka2 双工具交叉验证：

nextflow run nf-core/sarek -r 3.7.1 -profile docker \ --input samplesheet.csv --outdir results --genome GRCh38 \ --tools mutect2,strelka,snpeff

WES 外显子模式

外显子捕获数据必须指定--wes并给出目标区域 BED 文件，避免对非目标区域浪费计算：

nextflow run nf-core/sarek -r 3.7.1 -profile docker \ --input samplesheet.csv --outdir results --genome GRCh38 \ --wes --intervals /path/to/targets.bed \ --tools haplotypecaller,snpeff

sarek.yaml中为 WES 单独定义了wes_template运行模板（含--wes与--intervals两个占位符），并要求用户必须提供 intervals BED 文件。

群体联合胚系分析（Joint germline）

对队列（cohort）数据做联合基因分型，先在 gVCF 层面合并再一起调用，比逐样本独立 calling 对低频变异的灵敏度更高：

--tools haplotypecaller --joint_germline

工具矩阵：Sarek 支持的变异检测器

--tools是逗号分隔的工具列表，按用途分为四类：

从 sarek.yaml 的决策点配置可以看到，仓库为不同场景预置了推荐组合：胚系默认haplotypecaller,snpeff；检测到 tumor-normal 对时推荐mutect2,strelka,snpeff；需要高精度胚系 calling 且具备 GPU 时可选haplotypecaller,deepvariant,snpeff；需要覆盖结构变异的综合肿瘤分析则选mutect2,manta,snpeff。

关键参数速查

配套的通用运行参数（来自 SKILL.md 的 Step 5）：

# 资源上限（防止单任务过度占用节点） --max_cpus 8 --max_memory '32.GB' --max_time '24.h'

基因组参考的选择与准备

--genome使用的是 iGenomes key。运行前建议用仓库的 manage_genomes.py 检查并下载参考：

python scripts/manage_genomes.py check GRCh38 python scripts/manage_genomes.py download GRCh38 python scripts/manage_genomes.py params GRCh38 # 输出 --fasta/--gtf 或 --genome 参数

该脚本内置了 GRCh38、GRCh37、GRCm39/GRCm38（小鼠）、R64-1-1（酵母）、BDGP6（果蝇）等十余个物种的 iGenomes 元数据，别名解析（如hg38 → GRCh38）也一并支持；缓存目录可通过环境变量NF_CORE_GENOME_CACHE覆盖，默认~/.nf-core/genomes。若本地已安装参考文件，params命令会输出--fasta/--gtf具体路径，否则回退为--genome <id>让管线按需下载。

输出文件结构

运行结束后在--outdir指定的目录下，核心产物按模块分层：

results/ ├── preprocessing/ │ └── recalibrated/ # Analysis-ready BAMs │ └── *.recal.bam ├── variant_calling/ │ ├── haplotypecaller/ # Germline VCFs │ ├── mutect2/ # Somatic VCFs (filtered) │ └── strelka/ ├── annotation/ │ └── snpeff/ # Annotated VCFs └── multiqc/

各产物的用途与校验点（对应 sarek.yaml 的outputs配置）：

• preprocessing/recalibrated/*.recal.bam：经过 BQSR 的 analysis-ready BAM，可直接用于下游分析；
• variant_calling/*/*.vcf.gz：各 caller 的原始 VCF（Mutect2 目录下为过滤后结果）；
• annotation/snpeff/*.ann.vcf.gz：SnpEff 功能注释后的变异文件；
• multiqc/multiqc_report.html：全流程 QC 汇总报告，是完成性校验的必查文件。

验证运行是否成功：

ls results/multiqc/multiqc_report.html grep "Pipeline completed successfully" .nextflow.log

常见问题排查

BQSR 失败

BQSR 需要参考基因组对应的已知位点（known sites）文件；非标准参考基因组往往缺失该文件，导致步骤失败。处理方式：确认当前--genome是否有 known sites，非标准参考直接用--skip_bqsr跳过重校准。

Mutect2 无变异输出

最常见原因是 samplesheet 中 tumor/normal 配对错误。检查每行的status列：0 = normal，1 = tumor，确认每个 tumor 样本都对应了匹配的 normal 样本。仓库的_validate_sarek_specific校验会提前对这类问题给出警告，建议在运行前就用--validate检查一遍。

WGS 内存不足

全基因组比对与变异检测对内存需求极大，进程被 OOM 杀掉（退出码 137/143）时：

--max_memory '128.GB' --max_cpus 16

单样本常规分析可降至--max_memory '32.GB'/'64.GB'，小数据测试用'16.GB'起步即可。更系统的资源建议见 sarek.yaml 的resources段：最小内存 16 GB、推荐 64 GB、WGS 128 GB，推荐 CPU 16 核、磁盘预留 500 GB。

DeepVariant GPU 不可用

DeepVariant 的深度学习模型在 GPU 上运行最快，若未配置 NVIDIA Docker runtime 会报错。确认方式：检查 Docker 是否配置了 NVIDIA GPU runtime；无法使用 GPU 时可退回 CPU 模式（更慢，但可用）。

断点续跑

任何中途失败都可以利用 Nextflow 的缓存机制续跑，已完成的步骤不会重算：

nextflow run nf-core/sarek -r 3.7.1 ... -resume

若缓存被破坏需强制重来，则需清理work/目录与.nextflow*缓存文件后重新运行（详见 troubleshooting.md）。

参考资源

• 管线完整参数列表、输出文档与使用文档：见 sarek.yaml 中urls段对应的 nf-core 官方链接
• 姊妹管线说明：rnaseq.md（RNA-seq）、atacseq.md（ATAC-seq）
• 公共数据获取：geo-sra-acquisition.md
• 环境安装与通用排错：installation.md、troubleshooting.md

声明：本技能为教学与科研用途的示例实现，用于将 nf-core 生信管线集成进自动化分析工作流，投入生产前请针对自身场景进行充分验证，并遵循生信分析的常规质控规范对结果做独立核验。发表成果时请按各 nf-core 仓库CITATIONS.md中的要求引用相应管线。

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins