📚 课程目录第1章 pysam库概述与安装

一、pysam 库概述与安装

做生物信息的人，每天都要面对各种测序文件。BAM、SAM、VCF…… 说白了，这些文件格式就是基因组数据的容器。我入行那会儿，处理 VCF 还得手写 C 函数去解析，改个过滤逻辑就要重新编译，效率低得让人想砸键盘。

后来我遇到了 pysam，它就像一把瑞士军刀。底层调用了 htslib 的 C 接口，上层给你一套 Python 的 API，读 BAM、写 VCF、查索引，一行代码搞定。我个人的习惯是：只要项目里需要跟 VCF 打交道，先用 pysam 试试。

1.1 pysam 是什么

pysam 是 htslib 的 Python 包装器。htslib 是处理 SAM/BAM/CRAM/VCF/BCF 的 C 库，广泛用在 samtools、bcftools 这些工具里。pysam 把 C 级别的内存管理和文件格式细节全藏起来了，你调用的就是 Python 对象。

举个例子，你不必手动维护文件指针、不必担心压缩块的对齐。创建一个 VariantFile 对象，就能像遍历列表一样读 VCF 记录。为什么会这么爽？因为底层帮你做了所有 I/O 缓冲和格式解析。

特性	说明
底层引擎	htslib（C 库，高效稳定）
支持格式	BAM, SAM, CRAM, VCF, BCF, gVCF
索引支持	.bai, .csi, .tbi, .crai
主要模块	AlignmentFile, VariantFile, TabixFile, Pileup
跨平台	Linux, macOS, Windows (WSL 推荐)

适用场景

批量过滤 VCF 中的 SNP/INDEL，按质量、深度、缺失率筛选。
从 BAM 提取 alignments 后与 VCF 位点交叉验证。
计算 pileup 做碱基覆盖统计。
解析 gVCF 构建合并队列。
写自定义的变异注释脚本，比如合并多个样本的 GT 字段。

1.2 安装 pysam

安装 pysam 最稳的方法是 pip。但如果你在特定的 HPC 集群里，或者需要链接自己编译的 htslib，那可以考虑源码编译。我个人推荐：先用 pip，遇到问题再编译。

1.2.1 pip 安装

pip install pysam

这行命令会直接下载预编译的 wheel（Linux 和 macOS 通常都有），几秒就装好。我碰见过在旧版 CentOS 上装不上的情况，那是因为系统自带的 libc 版本太老。这时候要么升级系统，要么用源码编译。

小技巧：可以用 pip install --upgrade pysam 升级到最新版。我习惯在虚拟环境里装，避免污染全局。

1.2.2 源码编译

当你需要自定义 htslib 的编译选项时（比如启用 lzma、bzip2 支持），或者 pip wheel 不包含你的平台，就得走源码编译了。

# 先拉源码
git clone --recursive https://github.com/pysam-developers/pysam.git
cd pysam

# 编译安装
python setup.py build
python setup.py install

注意 --recursive 参数，它会同时拉下 htslib 的子模块。我曾经漏掉这个参数，结果编译报错说找不到 htslib/hts.h…… 嗯，踩过的坑记得特别牢。

如果你系统里已经装了自行编译的 htslib，可以指定路径：

HTSLIB_LIBRARY_DIR=/usr/local/lib \
HTSLIB_INCLUDE_DIR=/usr/local/include \
python setup.py build_ext --inplace

注意：源码编译需要 GCC、make、zlib-devel、curl-devel、openssl-devel 等依赖。在 Ubuntu 上可以提前运行：

sudo apt install build-essential zlib1g-dev libcurl4-openssl-dev libssl-dev liblzma-dev libbz2-dev

在 RHEL/CentOS 上类似，包名可能略有不同。

1.3 验证安装

装好后干一件简单的事：用 Python 导入 pysam 并打印版本号。

python -c "import pysam; print(pysam.__version__)"

如果输出版本号（比如 0.22.0），那就成功了。我一般还会顺手检查一下 htslib 版本：

python -c "import pysam; print(pysam.get_htslib_version())"

输出类似 1.17，说明底层 htslib 正确加载。

更进一步的验证：读一个小的 VCF 文件看看。假设你手头有 sample.vcf：

python -c "
import pysam
vcf = pysam.VariantFile('sample.vcf')
for rec in vcf.fetch():
    print(rec.chrom, rec.pos, rec.ref, rec.alts)
    break
vcf.close()
"

只要不出异常，而且打印出第一行变异的染色体、位置、REF 和 ALT 字段，那就说明安装完全可用。

避坑指南

我遇到过：在 macOS 上用 pip 安装后导入 pysam 时 crash，原因是 Xcode 命令行工具没装。运行 xcode-select --install 解决。
我遇到过：在 Anaconda 环境里用 pip 装 pysam，结果链接了系统 htslib 和 conda htslib 冲突。建议在 conda 环境里用 conda install -c conda-forge pysam，更省心。
我曾经：在 Docker 里编译 pysam 时忘记加 --recursive，折腾了半小时才意识到。记住这个参数，能省很多时间。

1.4 本章知识体系

我把这一章的核心逻辑画成了一张流程图。你可以看到从「选择安装方式」到「验证安装」的全过程，中间标注了常见的坑点和检查项。