mcpField
P
pysam

pysam

github.com/crazymsn数据与数据库2335 次安装22 周前更新
代码仓库

关于 pysam

这是一份 Pysam 技能指南，介绍用于读取、修改和写入基因组数据的 Python 模块。指南面向生物信息学工作，涵盖比对、变异与序列数据，以及区域查询、覆盖度分析和 samtools/bcftools 命令。

主要功能

  1. 01SAM/BAM/CRAM 比对文件处理
  2. 02VCF/BCF 变异数据处理
  3. 03FASTA/FASTQ 序列访问
  4. 04区域查询与覆盖度分析
  5. 05调用 samtools 和 bcftools

适用场景

  1. 01分析测序比对与覆盖度
  2. 02筛选或注释遗传变异
  3. 03提取基因区域参考序列
  4. 04构建生物信息学处理流程

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/crazymsn/academic-skills --skill pysam

安装后在 Claude Code 中输入/pysam确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
alignment_files.md
common_workflows.md
sequence_files.md
variant_files.md

详细介绍

Pysam

概述

Pysam 是一个 Python 模块，用于读取、操作和写入基因组数据集。通过 htslib 的 Pythonic 接口读取/写入 SAM/BAM/CRAM 比对文件、VCF/BCF 变异文件以及 FASTA/FASTQ 序列。查询经 tabix 索引的文件，执行 pileup 覆盖度分析，并运行 samtools/bcftools 命令。

何时使用此技能

在以下情况下应使用此技能：

  • 处理测序比对文件（BAM/CRAM）
  • 分析遗传变异（VCF/BCF）
  • 提取参考序列或基因区域
  • 处理原始测序数据（FASTQ）
  • 计算覆盖度或读段深度
  • 实现生物信息学分析工作流
  • 对测序数据进行质量控制
  • 开展变异检测和注释工作流

快速开始

安装
uv pip install pysam
基本示例

读取比对文件：

import pysam

# Open BAM file and fetch reads in region
samfile = pysam.AlignmentFile("example.bam", "rb")
for read in samfile.fetch("chr1", 1000, 2000):
    print(f"{read.query_name}: {read.reference_start}")
samfile.close()

读取变异文件：

# Open VCF file and iterate variants
vcf = pysam.VariantFile("variants.vcf")
for variant in vcf:
    print(f"{variant.chrom}:{variant.pos} {variant.ref}>{variant.alts}")
vcf.close()

查询参考序列：

# Open FASTA and extract sequence
fasta = pysam.FastaFile("reference.fasta")
sequence = fasta.fetch("chr1", 1000, 2000)
print(sequence)
fasta.close()

核心功能

1. 比对文件操作（SAM/BAM/CRAM）

使用 AlignmentFile 类处理已比对的测序读段。适用于分析比对结果、计算覆盖度、提取读段或进行质量控制。

常见操作：

  • 打开并读取 BAM/SAM/CRAM 文件
  • 获取特定基因组区域中的读段
  • 根据比对质量、标志或其他条件筛选读段
  • 写入已筛选或修改的比对数据
  • 计算覆盖度统计信息
  • 执行 pileup 分析（逐碱基覆盖度）
  • 访问读段序列、质量分数和比对信息

**参考：**有关以下内容的详细文档，请参阅 references/alignment_files.md：

  • 打开和读取比对文件
  • AlignedSegment 属性和方法
  • 使用 fetch() 按区域获取数据
  • 覆盖度 pileup 分析
  • 写入和创建 BAM 文件
  • 坐标系统和索引
  • 性能优化建议
2. 变异文件操作（VCF/BCF）

使用 VariantFile 类处理变异检测工作流生成的遗传变异。适用于变异分析、筛选、注释或群体遗传学。

常见操作：

  • 读取和写入 VCF/BCF 文件
  • 查询特定区域中的变异
  • 访问变异信息（位置、等位基因、质量）
  • 提取样本的基因型数据
  • 根据质量、等位基因频率或其他条件筛选变异
  • 使用附加信息注释变异
  • 对样本或区域进行子集筛选

**参考：**有关以下内容的详细文档，请参阅 references/variant_files.md：

  • 打开和读取变异文件
  • VariantRecord 属性和方法
  • 访问 INFO 和 FORMAT 字段
  • 处理基因型和样本
  • 创建和写入 VCF 文件
  • 筛选变异和获取子集
  • 多样本 VCF 操作
3. 序列文件操作（FASTA/FASTQ）

使用 FastaFile 随机访问参考序列，使用 FastxFile 读取原始测序数据。适用于提取基因序列、根据参考序列验证变异或处理原始读段。

常见操作：

  • 根据基因组坐标查询参考序列
  • 提取基因或目标区域的序列
  • 读取带有质量分数的 FASTQ 文件
  • 验证变异的参考等位基因
  • 计算序列统计信息
  • 根据质量或长度筛选读段
  • 在 FASTA 和 FASTQ 格式之间转换

**参考：**有关以下内容的详细文档，请参阅 references/sequence_files.md：

  • FASTA 文件访问和索引
  • 按区域提取序列
  • 处理基因的反向互补序列
  • 按顺序读取 FASTQ 文件
  • 质量分数转换和筛选
  • 处理经 tabix 索引的文件（BED、GTF、GFF）
  • 常见序列处理模式
4. 集成生物信息学工作流

Pysam 擅长整合多种文件类型，以进行全面的基因组分析。常见工作流会结合比对文件、变异文件和参考序列。

常见工作流：

  • 计算特定区域的覆盖度统计信息
  • 根据比对的 reads 验证变异
  • 使用覆盖度信息注释变异
  • 提取变异位置周围的序列
  • 根据多个条件筛选比对结果或变异
  • 生成用于可视化的覆盖度轨迹
  • 对多种数据类型进行质量控制

参考： 详细示例请参阅 references/common_workflows.md，包括：

  • 质量控制工作流（BAM 统计信息、参考序列一致性）
  • 覆盖度分析（逐碱基覆盖度、低覆盖度检测）
  • 变异分析（注释、按 reads 支持情况筛选）
  • 序列提取（变异上下文、基因序列）
  • reads 筛选与子集提取
  • 集成模式（BAM+VCF、VCF+BED 等）
  • 复杂工作流的性能优化

核心概念

坐标系统

重要： Pysam 使用 0 起始、左闭右开 坐标（Python 惯例）：

  • 起始位置从 0 开始（第一个碱基的位置为 0）
  • 结束位置不包含在范围内
  • 区域 1000-2000 包含碱基 1000-1999（共 1000 个碱基）

例外： fetch() 中的区域字符串遵循 samtools 惯例（从 1 开始）：

samfile.fetch("chr1", 999, 2000)      # 0-based: positions 999-1999
samfile.fetch("chr1:1000-2000")       # 1-based string: positions 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
性能注意事项
  1. 始终对随机访问操作使用已索引的文件
  2. 使用 pileup() 进行按列分析，而不是反复执行 fetch 操作
  3. 使用 count() 进行计数，而不是遍历并手动计数
  4. 分析相互独立的基因组区域时并行处理
  5. 显式关闭文件以释放资源
  6. 无索引时使用 until_eof=True 进行顺序处理
  7. 除非必要，否则避免使用多个迭代器（如有需要，使用 multiple_iterators=True）

常见问题

  1. 坐标混淆： 请记住不同上下文中从 0 开始和从 1 开始的坐标系统
  2. 缺少索引： 许多操作都需要索引文件，请先创建索引
  3. 部分重叠： fetch() 会返回与区域边界重叠的 reads，而不仅仅是完全位于区域内的 reads
  4. 迭代器作用域： 保持 pileup 迭代器的引用有效，以避免出现“PileupProxy accessed after iterator finished”错误
  5. 质量分数编辑： 更改 query_sequence 后，无法原地修改 query_qualities；请先创建副本
  6. 流限制： 流式处理仅支持 stdin/stdout，不支持任意 Python 文件对象
  7. 线程安全： 尽管 I/O 期间会释放 GIL，但尚未全面验证线程安全性

命令行工具

Pysam 提供对 samtools 和 bcftools 命令的访问：

# Sort BAM file
pysam.samtools.sort("-o", "sorted.bam", "input.bam")

# Index BAM
pysam.samtools.index("sorted.bam")

# View specific region
pysam.samtools.view("-b", "-o", "region.bam", "input.bam", "chr1:1000-2000")

# BCF tools
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 - 实用的生物信息学综合工作流示例，结合多种文件类型，包括质量控制、覆盖度分析、变异验证和序列提取

获取帮助

有关特定操作的详细信息，请参阅相应的参考文档：

  • 使用 BAM 文件或计算覆盖度 → alignment_files.md
  • 分析变异或基因型 → variant_files.md
  • 提取序列或处理 FASTQ → sequence_files.md
  • 整合多种文件类型的复杂工作流 → common_workflows.md

官方文档：https://pysam.readthedocs.io/

评论

支持 Markdown