用途：Pysam 是 Python 模块，用于读取、操作和写入基因组数据集，提供对 htslib 的 Python 接口，可处理 SAM/BAM/CRAM 比对文件、VCF/BCF 变异文件以及 FASTA/FASTQ 序列。适用于测序比对文件分析、遗传变异分析、参考序列或基因区域提取、原始测序数据处理、覆盖度或读深计算、生信分析流程实现、测序数据质控及变异检测注释流程。
主要能力：AlignmentFile 类支持打开读取 BAM/SAM/CRAM、按区域 fetch 读段、按比对质量或 flags 过滤、写入比对、计算覆盖度统计、pileup 逐碱基覆盖分析，以及访问读段序列、质量值和比对信息。VariantFile 类支持读写 VCF/BCF、区域查询变异、访问位置/等位基因/质量、提取样本基因型、按质量或等位基因频率过滤、注释变异及子集样本或区域。FastaFile 用于参考序列随机访问，FastxFile 用于读取原始测序数据，支持按坐标提取序列、读取带质量值的 FASTQ、验证变异参考等位基因、序列统计、按质量或长度过滤读段及 FASTA/FASTQ 格式转换。还可通过 pysam.samtools 和 pysam.bcftools 调用命令行工具，如排序、索引、区域查看和格式转换。
使用方式：安装命令为 uv pip install pysam。基本用法包括用 pysam.AlignmentFile("example.bam", "rb") 打开 BAM 并 fetch 区域，用 pysam.VariantFile("variants.vcf") 迭代变异，用 pysam.FastaFile("reference.fasta") 提取序列。随机访问需索引：BAM 需 .bai，CRAM 需 .crai，FASTA 需 .fai，VCF.gz 需 .tbi，BCF 需 .csi；无索引时可用 fetch(until_eof=True) 顺序读取。文件模式包括 "rb"、"r"、"rc"、"wb"、"w"、"wc"。
限制与注意：坐标系统为 0-based 半开区间，但 fetch() 区域字符串遵循 samtools 的 1-based 约定；VCF 文件格式用 1-based，而 VariantRecord.start 为 0-based。CRAM 自 pysam 0.24 / htslib 1.22 起默认输出 3.1 版本，且不再自动从 EBI 获取参考序列，需传 reference_filename= 或设置 REF_PATH/REF_CACHE。pileup 默认覆盖重叠读段跨越的所有位置，可用 truncate=True 限制窗口；count_coverage() 默认 quality_threshold=15，低质量碱基会被忽略。其他注意点包括保持 pileup 迭代器引用存活、修改 query_sequence 后不能原地改 query_qualities、流式仅支持 stdin/stdout、线程安全未完全验证。不适用场景：完整变异检测流程、多样本变异数组存储查询、覆盖度轨迹与 bigWig 生成、无 BAM/VCF 的序列记录解析、RNA-seq 转录本定量等，应改用其他专门技能。