第4章 Funcotator 运行命令：核心参数详解
说实话，刚接触 Funcotator 那会儿，我对着命令行愣了半天。
参数看着不多，但一个弄错，轻则报错，重则注释结果全乱。今天咱们就把这些核心选项掰开揉碎讲清楚。你跟着跑一遍，以后再用就不会翻车了。
4.1 最基本的骨架：输入与输出
一个 Funcotator 命令，说白了就三件事：你给我一个 VCF，告诉我用什么参考基因组，数据源在哪，然后指定输出文件。看这段基础命令：
java -jar Funcotator.jar \
--input sample.vcf \
--output sample.funcotated.vcf \
--ref-version hg19 \
--data-sources-path /data/funcotator/datasource/你看，四个参数构成了命令的骨架。我习惯在脚本里把参数分行写，一是可读性好，二是排查错误时一眼就能看出哪写错了。
输入输出参数一览：
--input：必需，输入的 VCF 文件（支持 .vcf 或 .vcf.gz）--output：必需，输出 VCF 路径，Funcotator 会把注释直接内嵌在 VCF 的 INFO 字段里--output-file-format：可选，默认是 VCF，还可以写成MAF或SEG。做临床解读时我一般选 VCF，方便后续用其他工具再加工--chunk-size：可选，控制每次读取的变异条数，默认 10000。在大型 WGS 数据上调大这个值能省些内存
我遇到过有人忘了写 --output，结果命令行跑完什么都没生成。嗯， Funcotator 不会自动帮你创建标准输出文件，这参数一定得写。
4.2 --ref-version：版本不对，满盘皆输
这个参数就一个值，但坑最多。它决定了数据源路径下按哪个子目录找参考序列。
允许的值：hg19、GRCh37、GRCh38、hg38。我个人建议统一用 GRCh37 或 GRCh38 这种标准叫法，避免混淆。为什么？
你看啊，hg19 和 GRCh37 本质上是一回事，但不同的数据源文件夹命名可能不一样。Funcotator 的 --data-sources-path 下，每个数据源目录里需要有一个 reference_version.txt 文件来标明版本。
我曾经在项目中遇到一个奇葩情况：输入 VCF 是 GRCh38 坐标，但 --ref-version 写了 hg19 ，Funcotator 居然没报错，因为它只拿着这个字符串去匹配数据源目录里的版本号。匹配不上时就直接跳过该数据源，导致大量基因没被注释，最终报告里一堆空白。
避坑指南： 写命令前，先确认你输入 VCF 的参考基因组版本。可以查看 VCF 头部的 ##reference 或 ##contig 行。然后严格保持一致。如果数据源里有多个版本子目录，记得检查 --data-sources-path 路径下按版本组织的目录名称。
4.3 --data-sources-path：数据源目录的结构门道
这个参数指向一个目录，目录下可以放多个数据源子文件夹。每个子文件夹必须有一套标准结构。拿我常用的一个目录举例：
/data/funcotator/datasource/
├── gencode/
│ ├── hg19/
│ │ ├── gencode.v19.annotation.gtf
│ │ └── reference_version.txt
│ └── hg38/
│ ├── gencode.v38.annotation.gtf
│ └── reference_version.txt
├── clinvar/
│ ├── hg19/
│ │ └── ...
│ └── hg38/
│ └── ...
├── gnomAD/
│ ├── hg19/
│ └── hg38/
│ └── ...
└── refseq/
└── ... --data-sources-path 后边直接写 /data/funcotator/datasource/，Funcotator 会自动扫描所有子目录，然后匹配 --ref-version 指定的版本。
这里有个容易忽略的点：如果你只配了一个数据源路径，Funcotator 会按数据源名称依次寻找。如果某个数据源缺失，它不会中止，而是跳过。我建议在跑正式分析前，先用 --list-data-sources 选项列出当前路径下所有可用的数据源：
java -jar Funcotator.jar \
--list-data-sources \
--data-sources-path /data/funcotator/datasource/ \
--ref-version hg19数据源加载规则：
- 每个数据源子目录名就是数据源 ID（如 gencode、clinvar）
- 目录内必须有版本子目录（hg19 / hg38）
- 版本子目录内必须有
reference_version.txt，内容只需要一行，写版本字符串，比如hg19或GRCh37 - 数据源的具体文件格式由 Funcotator 根据
DataSourceType自动识别
4.4 其他常用选项速查表
| 选项 | 说明 | 我的建议值 |
|---|---|---|
--transcript-selection-mode |
选择转录本的策略：CANONICAL（仅规范转录本）、BEST_EFFECT（选影响最大的）、ALL（所有转录本） |
临床解读通常用 CANONICAL，减少噪声 |
--annotation-lookup |
指定一个自定义的基因名称映射表，用于替换数据源里的基因符号 | 如果你们实验室有内部基因命名规范，可以用这个覆盖 |
--five-prime-flank-size |
定义上游侧翼区域大小，决定是否将变异视为启动子区变异，默认 2000 | 一般不动，但做非编码区分析时可调大到 5000 |
--three-prime-flank-size |
定义下游侧翼区域大小，同上 | 默认也是 2000 |
--remove-resource-requirements |
忽略数据源版本检查，快速测试用 | 别在生产环境用，容易注释不全 |
4.5 完整的实战命令示例
下面是我在项目里用的一条实际命令，带着注释复制就能用：
java -Xms4g -Xmx8g -jar /opt/Funcotator/Funcotator.jar \
--input /data/raw/WES_tumor_normal.somatic.vcf.gz \
--output /data/analysis/WES_tumor_normal.funcotated.vcf \
--ref-version hg38 \
--data-sources-path /data/funcotator/datasource/ \
--transcript-selection-mode CANONICAL \
--five-prime-flank-size 2000 \
--three-prime-flank-size 2000 \
--output-file-format VCF注意我加了 -Xms4g -Xmx8g，对大 VCF 文件来说内存给够。默认 2G 大概率会 OOM。
一个小技巧： 如果你数据源路径很大，第一次运行可以先指定 --verbosity DEBUG，看看 Funcotator 到底是从哪些路径加载了数据源。我上次就是靠这个 debug 日志发现某个数据源的 reference_version.txt 写成了 hg19\n（多了换行符），导致版本匹配失败。
4.6 参数关系总览
画这张图时我特意把 --data-sources-path 放到了必选参数行里。为什么呢？因为实战中如果不配这个，Funcotator 会直接报错退出。你想想看，没有数据源它怎么注释？所以它本质上就是必选的，尽管帮助文档把它标称了“可选”。避坑指南：任何跑失败的案子，先检查这两个参数：--ref-version 和 --data-sources-path。