Pysam 是一个用于读取、操作和写入基因组数据集的 Python 模块，提供面向 Python 的 htslib 接口，可读写 SAM/BAM/CRAM 比对文件、VCF/BCF 变异文件以及 FASTA/FASTQ 序列。它支持查询 tabix 索引文件、进行覆盖度 pileup 分析，并调用 samtools/bcftools 命令。
适用场景 适合处理测序比对文件（BAM/CRAM）、分析遗传变异（VCF/BCF）、提取参考序列或基因区域、处理原始测序数据（FASTQ）、计算覆盖度或读深、实现生物信息学分析流程、测序数据质控，以及变异检测与注释工作流。
快速开始 安装命令：uv pip install pysam
读取比对文件示例： import pysam samfile = pysam.AlignmentFile("example.bam", "rb") for read in samfile.fetch("chr1", 1000, 2000): print(f"{read.query_name}: {read.reference_start}") samfile.close()
读取变异文件示例： vcf = pysam.VariantFile("variants.vcf") for variant in vcf: print(f"{variant.chrom}:{variant.pos} {variant.ref}>{variant.alts}") vcf.close()
查询参考序列示例： fasta = pysam.FastaFile("reference.fasta") sequence = fasta.fetch("chr1", 1000, 2000) print(sequence) fasta.close()
核心能力
-
比对文件操作（SAM/BAM/CRAM）：使用 AlignmentFile 类处理已比对测序读段，适合分析比对结果、计算覆盖度、提取读段或质控。常见操作包括打开与读取 BAM/SAM/CRAM 文件、按基因组区域获取读段、按比对质量或标志等条件过滤读段、写入过滤或修改后的比对、计算覆盖度统计、进行 pileup 分析（逐碱基覆盖度）、访问读段序列与质量分数及比对信息。
-
变异文件操作（VCF/BCF）：使用 VariantFile 类处理变异检测流程产生的遗传变异，适合变异分析、过滤、注释或群体遗传学。常见操作包括读写 VCF/BCF 文件、查询特定区域的变异、访问变异信息（位置、等位基因、质量）、提取样本基因型数据、按质量或等位基因频率等条件过滤变异、为变异添加注释、对样本或区域取子集。
-
序列文件操作（FASTA/FASTQ）：使用 FastaFile 随机访问参考序列，使用 FastxFile 读取原始测序数据，适合提取基因序列、用参考序列验证变异或处理原始读段。常见操作包括按基因组坐标查询参考序列、提取基因或目标区域序列、读取带质量分数的 FASTQ 文件、验证变异参考等位基因、计算序列统计、按质量或长度过滤读段、在 FASTA 与 FASTQ 格式间转换。
-
集成生物信息学工作流：Pysam 擅长整合多种文件类型进行综合基因组分析，常见工作流结合比对文件、变异文件与参考序列，包括计算特定区域的覆盖度统计、用比对读段验证变异、为变异注释覆盖度信息、提取变异位置附近的序列、按多重条件过滤比对或变异、生成用于可视化的覆盖度轨道、跨多种数据类型进行质控。
关键概念 坐标系：Pysam 使用 0 基、半开区间坐标（Python 惯例）：起始位置为 0 基，结束位置不包含。区域 1000-2000 包含碱基 1000-1999（共 1000 个碱基）。例外：fetch() 中的区域字符串遵循 samtools 惯例（1 基），如 samfile.fetch("chr1", 999, 2000) 表示 0 基的 999-1999 位置，而 samfile.fetch("chr1:1000-2000") 为 1 基字符串，表示 1000-2000 位置。VCF 文件格式使用 1 基坐标，但 VariantRecord.start 为 0 基。
索引要求：随机访问特定基因组区域需要索引文件。BAM 需要 .bai 索引（用 pysam.index() 创建），CRAM 需要 .crai，FASTA 需要 .fai（用 pysam.faidx() 创建），VCF.gz 需要 .tbi tabix 索引（用 pysam.tabix_index() 创建），BCF 需要 .csi 索引。无索引时可使用 fetch(until_eof=True) 顺序读取。
文件模式：打开文件时指定格式，"rb" 读 BAM（二进制）、"r" 读 SAM（文本）、"rc" 读 CRAM、"wb" 写 BAM、"w" 写 SAM、"wc" 写 CRAM。
性能考虑：随机访问务必使用索引文件；用 pileup() 做逐列分析而非重复 fetch；用 count() 计数而非手动遍历；分析独立基因组区域时可并行处理；显式关闭文件以释放资源；无索引时用 until_eof=True 顺序处理；避免不必要的多迭代器（如需则用 multiple_iterators=True）。
常见陷阱：坐标系混淆（注意不同上下文中 0 基与 1 基）；缺少索引（许多操作需要索引文件，须先创建）；部分重叠（fetch() 返回与区域边界重叠的读段，而非仅完全包含的读段）；迭代器作用域（保持 pileup 迭代器引用存活，避免“PileupProxy accessed after iterator finished”错误）；质量分数编辑（修改 query_sequence 后不能就地修改 query_qualities，须先复制）；流限制（仅支持 stdin/stdout 流式处理，不支持任意 Python 文件对象）；线程安全（I/O 期间会释放 GIL，但全面线程安全性尚未完全验证）。
命令行工具 Pysam 提供对 samtools 和 bcftools 命令的访问： 排序 BAM：pysam.samtools.sort("-o", "sorted.bam", "input.bam") 索引 BAM：pysam.samtools.index("sorted.bam") 查看特定区域：pysam.samtools.view("-b", "-o", "region.bam", "input.bam", "chr1:1000-2000") BCF 工具：pysam.bcftools.view("-O", "z", "-o", "output.vcf.gz", "input.vcf") 错误处理示例： try: pysam.samtools.sort("-o", "output.bam", "input.bam") except pysam.SamtoolsError as e: print(f"Error: {e}")
资源 references/ 目录提供各主要能力的详细文档：alignment_files.md（SAM/BAM/CRAM 操作完整指南，含 AlignmentFile 类、AlignedSegment 属性、fetch 操作、pileup 分析及写入比对）、variant_files.md（VCF/BCF 操作完整指南，含 VariantFile 类、VariantRecord 属性、基因型处理、INFO/FORMAT 字段及多样本操作）、sequence_files.md（FASTA/FASTQ 操作完整指南，含 FastaFile 与 FastxFile 类、序列提取、质量分数处理及 tabix 索引文件访问）、common_workflows.md（整合多文件类型的实用工作流示例，含质控、覆盖度分析、变异验证及序列提取）。
官方文档：https://pysam.readthedocs.io/