用途：pysam 是 Python 基因组数据工具箱，基于 htslib 提供 Python 接口，用于读取、操作和写入测序比对、变异与序列数据，适合生物信息学分析流程，如测序数据质控、变异分析、覆盖度计算等。
主要能力：一、比对文件（SAM/BAM/CRAM），用 AlignmentFile 打开、按基因组区域 fetch 读取、按比对质量或 flags 过滤、写入过滤后的比对、计算覆盖度统计、pileup 逐碱基覆盖分析。二、变异文件（VCF/BCF），用 VariantFile 读写、按区域查询、访问位置与等位基因及质量、提取样本基因型、按质量或等位基因频率过滤、注释变异。三、序列文件（FASTA/FASTQ），用 FastaFile 按坐标随机访问参考序列，用 FastxFile 顺序读取带质量值的原始测序数据，校验变异参考等位基因、统计序列信息。四、整合工作流，结合比对、变异与参考序列做质控、覆盖度分析、变异校验和序列提取。还提供 samtools/bcftools 命令封装。
使用方式：安装命令为 uv pip install pysam。基本用法是导入 pysam 后用对应类打开文件并迭代，例如用 AlignmentFile 打开 BAM 并 fetch 区域、用 VariantFile 迭代变异、用 FastaFile 提取序列。命令行示例：pysam.samtools.sort("-o", "sorted.bam", "input.bam")；pysam.samtools.index("sorted.bam")；pysam.bcftools.view("-O", "z", "-o", "output.vcf.gz", "input.vcf")。错误可用 pysam.SamtoolsError 捕获。
坐标系与索引：pysam 使用 0 基、半开区间坐标，但 fetch() 的区域字符串遵循 samtools 的 1 基约定。随机访问需索引：BAM 需 .bai，CRAM 需 .crai，FASTA 需 .fai，VCF.gz 需 .tbi，BCF 需 .csi；无索引时可用 fetch(until_eof=True) 顺序读取。文件模式包括 rb/r/rc 和 wb/w/wc。
限制与注意事项：需注意 0 基与 1 基坐标差异；缺少索引会限制区域操作；fetch() 返回与区域边界重叠的读段而非完全包含的读段；pileup 迭代器引用需保持存活；修改 query_sequence 后不能原地改 query_qualities，需先复制；流式仅支持 stdin/stdout；线程安全尚未完全验证。官方文档见 https://pysam.readthedocs.io/。