📚 课程目录第2章环境搭建

环境搭建：GATK安装、Java依赖、Funcotator数据源下载

环境搭建这块，说白了就是三个事：把GATK装好、把Java版本搞对、把数据源拉下来。

这三个缺一个，后面都跑不起来。我刚开始搞Funcotator时，就在Java版本上栽过跟头。嗯，咱们一步步来。

1. Java版本：第一步就得确认

GATK4 对 Java 的要求是 JDK 8 或 JDK 11。太高或太低都不行。

为什么？GATK 在编译时用了特定版本的 Java 特性。你拿 Java 17 去跑，有些底层库会直接报错。

我在项目中遇到过团队有人装了 Java 17，结果 Funcotator 运行时抛出 UnsupportedClassVersionError。折腾了半天才发现是版本不匹配。

检查自己当前的 Java 版本，用这个命令：

java -version

如果输出里显示 openjdk version "1.8" 或 "11"，就对了。如果是别的数字，需要重新装。

⚠️ 注意：不要用 OpenJDK 17、19、21 等。你可能会遇到奇怪的类加载异常。我建议直接用 JDK 11，它对 GATK 4.x 兼容最稳。

2. GATK 安装：简单但别搞错

GATK 的安装包是预编译好的。你不需要自己编译源码。

从官网或 GitHub Release 下载 gatk-4.x.x.zip。解压后就能用。

# 下载示例（以 v4.3.0.0 为例）
wget https://github.com/broadinstitute/gatk/releases/download/4.3.0.0/gatk-4.3.0.0.zip

# 解压
unzip gatk-4.3.0.0.zip

# 进入目录
cd gatk-4.3.0.0

解压后，你会看到 gatk 这个可执行文件（Linux/Mac）或 gatk.bat（Windows）。

验证安装：

./gatk --version

如果能正常输出版本号，说明 GATK 本身没问题。

💡 小技巧：我习惯把 gatk 的路径加到 PATH 环境变量里。这样在任何目录都能直接执行，不用每次输完整路径。

3. Funcotator 数据源：最花时间的部分

Funcotator 需要一套参考数据，包括基因注释、转录本信息、已知变异数据库等。

数据源有两个来源：

GATK 官方的预打包数据（推荐，省事）
自己从 UCSC、NCBI 等源头定制（需要大量脚本处理）

我个人建议用官方预打包数据。除非你有非常特殊的基因组版本或注释需求，否则不要自己造轮子。

下载官方数据源有两种方式：

方式一：用 GATK 自带的下载脚本

# 下载 hg38 数据源
./gatk FuncotatorDataSourceDownloader \
  --somatic \
  --hg38 \
  --extract-after-download

# 下载 hg19 数据源
./gatk FuncotatorDataSourceDownloader \
  --somatic \
  --hg19 \
  --extract-after-download

方式二：直接从 Broad 的 FTP 下载

# hg38 版本
wget ftp://gsapubftp-anonymous@ftp.broadinstitute.org:/pub/Data_Funcotator/hg38/funcotator_dataSources.v1.7.20200521s.tar.gz

# hg19 版本
wget ftp://gsapubftp-anonymous@ftp.broadinstitute.org:/pub/Data_Funcotator/hg19/funcotator_dataSources.v1.7.20200521g.tar.gz

解压：

tar -xzf funcotator_dataSources.v1.7.20200521s.tar.gz

解压后的目录结构大致是这样：

funcotator_dataSources.v1.7.20200521s/
├── funcotator_local.pm
├── gencode/
├── lrg/
├── phastCons/
├── ...
└── README.txt

⚠️ 警告：数据源压缩包约 2-3 GB，解压后约 6-8 GB。确保硬盘空间充裕。我曾经在服务器上直接下载到 /tmp 目录，结果解压到一半空间占满，功亏一篑。

  🔑 关键点：下载后，记住解压路径。后面运行 Funcotator 时，需要通过 --data-sources-path 参数指定这个目录。

4. 完整环境验证

所有东西都装好后，跑一个简单的测试，确认整个链路通顺。

./gatk Funcotator \
  -R /path/to/reference/hg38.fa \
  -V /path/to/input.vcf \
  -O /path/to/output.vcf \
  --data-sources-path /path/to/funcotator_dataSources.v1.7.20200521s/ \
  --ref-version hg38

如果这个命令没报错，说明环境搭建成功了。

5. 核心环节速览表

我把环境搭建的三个核心环节整理成了表格，方便你快速对照检查。

环节	核心要求	关键命令/路径	常见坑
Java 版本	JDK 8 或 JDK 11	`java -version`	版本过高或安装多个 JDK 导致冲突
GATK 安装	下载预编译包并解压	`./gatk --version`	忘记设置 PATH 或解压后目录被误删
Funcotator 数据源	下载并解压到指定目录	`FuncotatorDataSourceDownloader` 或 FTP 下载	硬盘空间不足、网络中断导致下载不完整

💡 经验之谈：建议把 Java、GATK、数据源这三个路径写到一个 env.sh 脚本里，每次跑分析前 source 一下。这样不会漏配环境变量，也算是个好习惯。

6. 本章知识结构图

下面这张图把环境搭建的流程和关键节点串起来了。你可以用它对照检查自己的进度。