📚 课程目录第3章环境搭建与工具安装

3 环境搭建与工具安装：bcftools、vcftools、Python库等

做多批次VCF一致性分析，第一步就是把用到的工具都装好。别小看这步，我见过不少同学花半天装环境，最后发现版本冲突，反而耽误正事。这里我把自己的安装经验、踩过的坑、验证方法都摊开讲，你跟着走一遍，基本不会出问题。

3.1 聊聊这三类工具的角色

bcftools、vcftools 和 Python 库，各管一摊，谁也替不了谁。我通常把它们的角色比作“三件套”：

工具	核心用途	我的常用场景
bcftools	VCF 文件视图、过滤、索引、合并、统计	批量合并批次 VCF、提取样本子集、计算一致性统计量
vcftools	VCF 格式转换、群体遗传参数计算、格式校验	转 PLINK 格式做下游交互、去除低质量位点
Python 库（pyVCF / pandas / matplotlib）	灵活解析、脚本化处理、可视化	自定义一致性评分、画 heatmap 和 Venn 图

搞清楚分工，安装时就不会盲目求全。我个人习惯是：先装 bcftools 和 vcftools，确认能跑通，再配 Python 环境。

3.2 bcftools：安装与验证

bcftools 安装方式很多，我推荐从源码编译，因为最新版修复了不少 VCF 解析 bug。你在 Ubuntu 上可以这样：

# 依赖安装
sudo apt-get update
sudo apt-get install -y gcc make zlib1g-dev libbz2-dev liblzma-dev libcurl4-openssl-dev

# 下载源码（以 1.20 为例）
wget https://github.com/samtools/bcftools/releases/download/1.20/bcftools-1.20.tar.bz2
tar -xjf bcftools-1.20.tar.bz2
cd bcftools-1.20

# 编译安装到 /usr/local/bin
./configure --prefix=/usr/local
make -j$(nproc)
sudo make install

装完记得验证一下：

bcftools --version | head -n 2

你应该能看到类似 bcftools 1.20 的字样。我在生产环境遇到过老版本用 bcftools norm 把 VCF 拆乱的情况，所以建议至少 1.16 以上。

小技巧： 如果你是 macOS，用 brew install bcftools 最省事。但记得装完后运行 bcftools +version 检查是否支持 HTSlib 的完整特性——有些 brew 包会去掉 tabix 支持，导致后面索引报错。

3.3 vcftools：安装与踩坑记录

vcftools 已经进入维护阶段，但不妨碍它好用。我建议用源码安装：

git clone https://github.com/vcftools/vcftools.git
cd vcftools
./autogen.sh
./configure --prefix=/usr/local
make
sudo make install

曾经有一次我图省事，用 sudo apt install vcftools，结果装上的是 0.1.15 的老版本，--max-missing 参数行为跟新版不一样，害我排查了半小时。嗯，还是手动编译来得踏实。

装完后跑一下：

vcftools --version

输出正确即安装成功。vcftools 没有单独的 man page，不过 vcftools --help 足够用了。

注意： vcftools 对 chr 前缀很敏感。如果你的 VCF 里面染色体是 chr1，而脚本里用 1，它会直接跳过整个染色体。这问题我吃过亏——在批量分析里，一定要先统一染色体命名格式。

3.4 Python 环境：pyVCF + pandas + matplotlib

Python 部分我习惯用 conda 管理，干净、隔离。创建专用环境：

conda create -n vcf_analysis python=3.10 -y
conda activate vcf_analysis

然后安装三个核心库：

conda install -c bioconda pyvcf
conda install pandas matplotlib

为什么要 pyVCF 而不是 cyvcf2？个人经验：pyVCF 纯 Python，安装零坑，调试方便。如果 VCF 文件非常大（超过 5GB），可以换 cyvcf2，那个基于 C 扩展，速度快 10 倍。

验证 Python 环境是否就绪：

python -c "import pyvcf; import pandas; import matplotlib; print('All imports OK')"

如果没报错，就说明基础环境搭好了。我一般还会装一个 seaborn 用来画一致性热图，后面章节会用到。

3.5 快速验证：一个真实的“全家桶”测试

为了确保所有工具都能协同工作，我会跑一个小脚本，用单个样本的 VCF 做校验。你可以把下面的内容保存为 check_env.sh：

#!/bin/bash
echo "=== Testing bcftools ==="
bcftools --version | head -n 1

echo "=== Testing vcftools ==="
vcftools --version 2>&1 | head -n 1

echo "=== Testing Python packages ==="
python3 -c "
import pyvcf
import pandas as pd
import matplotlib
print('pyVCF version:', pyvcf.__version__ if hasattr(pyvcf, '__version__') else 'installed')
print('Pandas version:', pd.__version__)
print('Matplotlib version:', matplotlib.__version__)
"

echo "=== All checks passed ==="

跑一下：

bash check_env.sh

如果全部通过，恭喜你，环境就算齐活了。我这几轮折腾下来，最常翻车的是 pyvcf 版本——旧版（< 0.6.8）读不了 Python 3.10 的字节码，所以直接装最新版最省心。

3.6 工具链关系图

下面这张图是我自己梳理的环境依赖与数据流向，你一看就明白各工具在一致性分析中的位置。

3.7 常见问题与避坑指南

PATH 冲突： 我自己就曾把 conda 安装的 bcftools 和系统自带的弄混，导致版本检错。建议用 which bcftools 确认你调用的路径是哪个。
HTSlib 版本不匹配： bcftools 依赖 libhts，编译时如果系统中有多个版本，用 ldd $(which bcftools) 查看动态链接库。我曾经由于 libhts 版本太旧，导致 bcftools merge 报段错误——重编一次搞定。
Python 虚拟环境混乱： 一定要用 conda 或 venv，不要在系统 Python 里直接装 pyVCF。血的教训——公司服务器上系统 Python 被污染，导致同事的脚本站不起来。

  关键总结： 工具安装本身不复杂，但需要关注版本兼容性和环境隔离。花 10 分钟按上面步骤走一遍，后面几十个批次的 VCF 分析就能顺畅推进。我已经用这套环境处理过超过 500 个 VCF 文件，没出过大问题。

嗯，装好工具只是第一步。下一步你会拿到真实的 VCF 文件，开始做批次间的一致性对比——那才是真正有意思的地方。