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

GATK环境搭建：安装GATK4、配置Java环境、依赖库管理、容器化部署

环境搭建这步，说难不难，但踩过的坑是真不少。我刚开始用GATK时，光Java版本就折腾了两次，后来才发现官方文档里藏着关键小字。今天咱们就一步步把环境理清楚，保证你搭完后跑起流程来不卡顿。

一、Java环境配置——GATK的“心脏”

GATK4依赖Java 8或11，我个人习惯用Java 11，因为后续其他生信工具兼容性更好。检查系统是否已有Java：

java -version
# 期望输出类似：openjdk version "11.0.18" 2023-04-18 LTS

如果没有，用包管理器安装。Ubuntu/Debian系：

sudo apt update
sudo apt install openjdk-11-jdk -y

CentOS/RHEL系：

sudo yum install java-11-openjdk-devel -y

避坑： 我曾经装过Java 14，结果GATK跑某些模块时直接报“unsupported class version”。所以别贪新，老老实实用官方推荐的版本。

配置JAVA_HOME环境变量：

# 找到Java安装路径
update-alternatives --config java
# 通常路径是 /usr/lib/jvm/java-11-openjdk-amd64

# 写入 ~/.bashrc 或 ~/.profile
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

source ~/.bashrc
java -version  # 验证

二、安装GATK4——两种方式任你选

方式一：直接下载编译好的jar包。我通常用这种方式，简单直接：

wget https://github.com/broadinstitute/gatk/releases/download/4.5.0.0/gatk-4.5.0.0.zip
unzip gatk-4.5.0.0.zip
cd gatk-4.5.0.0
./gatk --list  # 测试安装是否成功

方式二：从源码编译（适合需要定制参数或调试的用户）：

git clone https://github.com/broadinstitute/gatk.git
cd gatk
./gradlew shadowJar
# 编译产物在 build/libs/ 下
# 运行方式：java -jar build/libs/gatk-package-4.5.0.0-local.jar --list

小提示： 我建议将./gatk脚本软链接到/usr/local/bin，这样全局都能调用：

sudo ln -s $(pwd)/gatk /usr/local/bin/gatk

三、依赖库管理——R和Python一个都不能少

GATK4很多流程（比如VQSR、CNV分析）需要R和Python库支持。我曾经在跑VQSR时因为忘记装ggplot2，结果脚本跑到一半卡住。咱们提前打好基础。

3.1 R及R包

# 安装R
sudo apt install r-base -y

# 安装常用包
sudo R -e "install.packages(c('ggplot2','gplots','reshape2'), repos='https://cloud.r-project.org')"

3.2 Python及pip包

# 确保Python3可用
python3 --version

# 安装常用包
pip3 install numpy pandas matplotlib scipy scikit-learn

为什么需要这些？说白了，GATK的文档模块（DocGen）和绘图模块底层调用了它们。少了任何一个，你可能会遇到莫名其妙的“ModuleNotFoundError”。

依赖项	用途	建议版本
Java 8/11	GATK核心运行环境	11 LTS
R ≥ 3.6	VQSR、Counts可视化	4.x
Python ≥ 3.7	CNV、DocGen脚本	3.9
ggplot2	QC图、方差图	最新
numpy/pandas	数据预处理	最新

四、容器化部署——让环境“拎包即用”

如果你跟我一样，需要在多台机器上跑分析，或者想保证团队成员环境一致，容容器化是最好选择。GATK官方提供了Docker镜像和Singularity定义文件。

4.1 Docker部署

# 拉取官方镜像
docker pull broadinstitute/gatk:4.5.0.0

# 运行测试
docker run broadinstitute/gatk:4.5.0.0 gatk --list

# 挂载本地数据目录
docker run -v /local/data:/data broadinstitute/gatk:4.5.0.0 \
    gatk HaplotypeCaller -R /data/ref.fasta -I /data/input.bam -O /data/output.vcf

  个人经验： 用Docker跑GATK时，记得加上--user $(id -u):$(id -g)，这样生成的输出文件权限与你当前用户一致，省去后面sudo的麻烦。

4.2 Singularity部署（更适合HPC环境）

# 从Docker Hub构建Singularity镜像
singularity build gatk-4.5.0.0.sif docker://broadinstitute/gatk:4.5.0.0

# 运行
singularity exec gatk-4.5.0.0.sif gatk --list

# 绑定目录
singularity exec --bind /local/data:/data gatk-4.5.0.0.sif \
    gatk HaplotypeCaller -R /data/ref.fasta -I /data/input.bam -O /data/output.vcf

Singularity的优势在于：不需要root权限，更适合集群调度器（如Slurm）。我之前的项目在超算中心做全外显子组分析，管理员不让用Docker，我们用Singularity完美解决了。

特性	Docker	Singularity
权限要求	需要root（或sudo组）	普通用户可用
镜像格式	分层文件系统	单文件.sif
HPC友好度	低（需特权模式）	高（原生支持MPI等）
GPU支持	需额外配置nvidia-docker	默认支持（--nv）
典型场景	本地开发、CI/CD	集群生产环境

重要提醒： 如果你用容器化部署，不再需要手动安装Java、R、Python——镜像内已经包含全部依赖。但要注意内存限制：Docker默认可能限制容器内存，记得加上--memory=32g等参数。

五、环境搭建整体流程

下面这张图帮你看清整个环境搭建的决策路线：

从图里可以清楚看到：如果你打算直接跑GATK，准备好系统后安装Java，然后选择下载jar或源码编译，再装好依赖库。如果团队协作或上集群，建议直接上容器化——Docker或Singularity二选一，省去后续所有环境冲突的烦恼。

嗯，环境搭建就先聊到这儿。记住：Java版本别选错，容器化是个好东西，依赖库提前装好能让你少掉很多头发。我的经验告诉我——环境搭好了，后续的参数调优才能安心放手折腾。