cyvcf2 常用知识点

以下是 cyvcf2 常用的操作汇总，涵盖加载文件、解析变异、访问基因型、筛选变异、修改文件等核心功能，附带简洁的代码示例。内容按功能模块组织，力求简明实用，方便快速参考。假设用户已熟悉 cyvcf2 的基本背景（如 VCF/BCF 文件解析），本文直接聚焦操作。

---

1. 加载 VCF/BCF 文件

• 基本加载：打开 VCF 或 BCF 文件，支持 .vcf、.vcf.gz 和 .bcf 格式。

  from cyvcf2 import VCF
  vcf = VCF('example.vcf.gz')  # 加载文件
  

• 指定样本子集：仅加载部分样本。

  vcf = VCF('example.vcf.gz', samples=['sample1', 'sample2'])
  

• 启用多线程：加速读取。

  vcf = VCF('example.vcf.gz', threads=4)
  

• 延迟解析：节省内存，延迟解包记录。

  vcf = VCF('example.vcf.gz', lazy=True)
  

• 严格基因型模式：将含缺失等位基因的基因型（如 0/.）标记为 UNKNOWN。

  vcf = VCF('example.vcf.gz', strict_gt=True)
  

---

2. 迭代和访问变异信息

• 迭代所有变异：逐条读取变异记录。

  for variant in vcf:
      print(variant.CHROM, variant.POS, variant.REF, variant.ALT, variant.ID, variant.QUAL)
  

• 区域查询：提取特定染色体区域的变异。

  for variant in vcf('chr1:1000000-2000000'):
      print(variant.CHROM, variant.POS)
  

• 访问 INFO 字段：获取变异级别的元数据。

  for variant in vcf:
      dp = variant.INFO.get('DP')  # 深度
      ac = variant.INFO.get('AC')  # 等位基因计数
      print(dp, ac)
  

---

3. 处理基因型信息

• 获取基因型：返回基因型数组（0=纯合参考，1=杂合，2=纯合替代，3=未知）。

  for variant in vcf:
      gt_types = variant.gt_types  # NumPy 数组
      print(gt_types)  # 示例输出：[0, 1, 2]
  

• 获取深度信息：参考和替代等位基因的深度。

  for variant in vcf:
      ref_depths = variant.gt_ref_depths
      alt_depths = variant.gt_alt_depths
      print(ref_depths, alt_depths)
  

• 计算变异等位基因频率 (VAF)：

  for variant in vcf:
      vaf = variant.gt_alt_freqs
      print(vaf)  # 示例输出：[0.04081633]
  

• 获取相位和基因型质量：

  for variant in vcf:
      phases = variant.gt_phases  # 是否分相
      quals = variant.gt_quals    # 基因型质量
      print(phases, quals)
  

• 获取基因型碱基：

  for variant in vcf:
      gt_bases = variant.gt_bases  # 碱基表示（如 ['A/A', 'A/G']）
      print(gt_bases)
  

注意：基因型相关数组为 NumPy 格式，需复制以避免数据失效：

import numpy as np
for variant in vcf:
    gt_copy = np.array(variant.gt_types)  # 安全复制

---

4. 筛选变异

• 基于质量和类型：筛选高质量 SNP 变异。

  for variant in vcf:
      if variant.QUAL >= 30 and not variant.is_indel:  # 高质量，非 INDEL
          print(variant.CHROM, variant.POS)
  

• 基于基因型和深度：筛选杂合变异且替代深度大于 10。

  for variant in vcf:
      gt_types = variant.gt_types
      alt_depths = variant.gt_alt_depths
      for i, gt in enumerate(gt_types):
          if gt == 1 and alt_depths[i] > 10:
              print(f"Sample {i} is heterozygous at {variant.CHROM}:{variant.POS}")
  

• 基于 INFO 字段：筛选特定条件的变异。

  for variant in vcf:
      if variant.INFO.get('AF', 0) > 0.01:  # 等位基因频率 > 1%
          print(variant.CHROM, variant.POS)
  

• 筛选 de novo 变异：子代杂合，父母纯合参考。

  for variant in vcf:
      if (variant.gt_depths[0] >= 10 and variant.gt_depths[1] >= 10 and 
          variant.gt_depths[2] >= 10):  # 确保子代、父母深度足够
          if (variant.gt_types[0] == 1 and variant.gt_types[1] == 0 and 
              variant.gt_types[2] == 0 and 
              variant.gt_alt_depths[1] == 0 and variant.gt_alt_depths[2] == 0):
              print(f"De novo at {variant.CHROM}:{variant.POS}")
  

---

5. 修改和写入 VCF 文件

• 添加 INFO 字段：在 VCF 中添加新字段（如基因注释）。

  from cyvcf2 import VCF, Writer
  vcf = VCF('input.vcf.gz')
  vcf.add_info_to_header({'ID': 'GENE', 'Description': 'Overlapping gene', 
                          'Type': 'Character', 'Number': '1'})
  w = Writer('output.vcf', vcf)
  for variant in vcf:
      genes = get_gene_intersections(variant)  # 自定义函数
      if genes:
          variant.INFO['GENE'] = ','.join(genes)
      w.write_record(variant)
  w.close()
  vcf.close()
  

• 添加 FORMAT 字段：添加样本级字段。

  vcf.add_format_to_header({'ID': 'CUSTOM', 'Description': 'Custom field', 
                            'Type': 'Integer', 'Number': '1'})
  w = Writer('output.vcf', vcf)
  for variant in vcf:
      custom_values = calculate_custom_values(variant)  # 自定义计算
      variant.set_format('CUSTOM', custom_values)  # 设置新字段值
      w.write_record(variant)
  w.close()
  vcf.close()
  

---

6. 高级查询与统计

• 统计变异类型：计算 SNP 和 INDEL 数量。

  snp_count, indel_count = 0, 0
  for variant in vcf:
      if variant.is_snp:
          snp_count += 1
      elif variant.is_indel:
          indel_count += 1
  print(f"SNP: {snp_count}, INDEL: {indel_count}")
  

• 计算等位基因频率：基于基因型统计。

  for variant in vcf:
      af = variant.aaf  # 变异等位基因频率
      print(f"AAF at {variant.CHROM}:{variant.POS}: {af}")
  

• 样本级统计：统计每个样本的杂合变异数。

  het_counts = np.zeros(len(vcf.samples))
  for variant in vcf:
      het_counts += (variant.gt_types == 1)
  for sample, count in zip(vcf.samples, het_counts):
      print(f"{sample}: {count} heterozygous variants")
  

---

7. 常见注意事项

• NumPy 数组管理：基因型相关数组（如 gt_types）需复制以避免失效。

  gt_copy = np.array(variant.gt_types)
  

• 文件关闭：使用完 VCF 和 Writer 对象后需显式关闭。

  vcf.close()
  w.close()
  

• 字段类型检查：访问 INFO 或 FORMAT 字段时，确保字段存在并检查类型（整数、浮点数或字符串）。

  value = variant.INFO.get('DP', None)
  if value is not None:
      print(f"Depth: {value}")
  

• 版本兼容性：确保 cyvcf2 和 htslib 版本匹配（cyvcf2 >= 0.20.0 需要 htslib >= 1.10）。
• 编码限制：不支持非 ASCII 字符的 UTF-8 编码字段。

---

8. 典型应用场景

• 变异筛选：筛选高质量变异或特定基因型（如 de novo 变异）。
• VCF 修改：添加注释或过滤记录。
• 统计分析：计算变异频率、样本杂合率等。
• 区域提取：提取特定基因组区域的变异用于下游分析。

---

9. 参考资源

• 官方文档：http://brentp.github.io/cyvcf2/
• GitHub：https://github.com/brentp/cyvcf2
• 示例：https://github.com/genomoncology/using-cyvcf2

---

10. 总结

cyvcf2 提供了高效、灵活的 VCF/BCF 文件操作接口，适合处理大规模遗传变异数据。常用操作包括加载文件、迭代变异、访问基因型、筛选变异和修改文件。注意 NumPy 数组管理、文件关闭和字段类型检查，以确保代码健壮性。