pysam

Kit de ferramentas para arquivos genômicos. Leia/escreva alinhamentos SAM/BAM/CRAM, variantes VCF/BCF, sequências FASTA/FASTQ, extraia regiões, calcule cobertura, para pipelines de processamento de da

SKILL.md

GitHub

Pysam

Visão Geral

Pysam é um módulo Python para ler, manipular e escrever conjuntos de dados genômicos. Leia/escreva arquivos de alinhamento SAM/BAM/CRAM, arquivos de variantes VCF/BCF e sequências FASTA/FASTQ com uma interface Pythônica para htslib. Consulte arquivos indexados por tabix, execute análise de pileup para cobertura e execute comandos samtools/bcftools.

Quando Usar Esta Competência

Esta competência deve ser usada quando:

  • Trabalhar com arquivos de alinhamento de sequenciamento (BAM/CRAM)
  • Analisar variantes genéticas (VCF/BCF)
  • Extrair sequências de referência ou regiões de genes
  • Processar dados de sequenciamento bruto (FASTQ)
  • Calcular cobertura ou profundidade de leitura
  • Implementar pipelines de análise bioinformática
  • Controle de qualidade de dados de sequenciamento
  • Workflows de chamada e anotação de variantes

Início Rápido

Instalação

uv pip install pysam

Exemplos Básicos

Leia arquivo de alinhamento:

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()

Leia arquivo de variantes:

# 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()

Consulte sequência de referência:

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

Capacidades Principais

1. Operações com Arquivos de Alinhamento (SAM/BAM/CRAM)

Use a classe AlignmentFile para trabalhar com leituras de sequenciamento alinhadas. Isto é apropriado para analisar resultados de mapeamento, calcular cobertura, extrair leituras ou controle de qualidade.

Operações comuns:

  • Abrir e ler arquivos BAM/SAM/CRAM
  • Buscar leituras de regiões genômicas específicas
  • Filtrar leituras por qualidade de mapeamento, flags ou outros critérios
  • Escrever alinhamentos filtrados ou modificados
  • Calcular estatísticas de cobertura
  • Realizar análise de pileup (cobertura base a base)
  • Acessar sequências de leitura, pontuações de qualidade e informações de alinhamento

Referência: Veja references/alignment_files.md para documentação detalhada sobre:

  • Abrir e ler arquivos de alinhamento
  • Atributos e métodos de AlignedSegment
  • Busca baseada em região com fetch()
  • Análise de pileup para cobertura
  • Escrita e criação de arquivos BAM
  • Sistemas de coordenadas e indexação
  • Dicas de otimização de desempenho

2. Operações com Arquivos de Variantes (VCF/BCF)

Use a classe VariantFile para trabalhar com variantes genéticas de pipelines de chamada de variantes. Isto é apropriado para análise de variantes, filtragem, anotação ou genética de populações.

Operações comuns:

  • Ler e escrever arquivos VCF/BCF
  • Consultar variantes em regiões específicas
  • Acessar informações de variantes (posição, alelos, qualidade)
  • Extrair dados de genótipo para amostras
  • Filtrar variantes por qualidade, frequência de alelo ou outros critérios
  • Anotar variantes com informações adicionais
  • Subconjuntar amostras ou regiões

Referência: Veja references/variant_files.md para documentação detalhada sobre:

  • Abrir e ler arquivos de variantes
  • Atributos e métodos de VariantRecord
  • Acessar campos INFO e FORMAT
  • Trabalhar com genótipos e amostras
  • Criar e escrever arquivos VCF
  • Filtrar e subconjuntar variantes
  • Operações com VCF multi-amostra

3. Operações com Arquivos de Sequência (FASTA/FASTQ)

Use FastaFile para acesso aleatório a sequências de referência e FastxFile para ler dados de sequenciamento bruto. Isto é apropriado para extrair sequências de genes, validar variantes contra referência ou processar leituras brutas.

Operações comuns:

  • Consultar sequências de referência por coordenadas genômicas
  • Extrair sequências para genes ou regiões de interesse
  • Ler arquivos FASTQ com pontuações de qualidade
  • Validar alelos de referência de variantes
  • Calcular estatísticas de sequência
  • Filtrar leituras por qualidade ou comprimento
  • Converter entre formatos FASTA e FASTQ

Referência: Veja references/sequence_files.md para documentação detalhada sobre:

  • Acesso e indexação de arquivos FASTA
  • Extração de sequências por região
  • Manejo de complemento reverso para genes
  • Leitura sequencial de arquivos FASTQ
  • Conversão e filtragem de pontuação de qualidade
  • Trabalho com arquivos indexados por tabix (BED, GTF, GFF)
  • Padrões comuns de processamento de sequência

4. Workflows Bioinformáticos Integrados

Pysam é excelente em integrar múltiplos tipos de arquivo para análises genômicas abrangentes. Workflows comuns combinam arquivos de alinhamento, arquivos de variantes e sequências de referência.

Workflows comuns:

  • Calcular estatísticas de cobertura para regiões específicas
  • Validar variantes contra leituras alinhadas
  • Anotar variantes com informações de cobertura
  • Extrair sequências ao redor de posições de variantes
  • Filtrar alinhamentos ou variantes com base em múltiplos critérios
  • Gerar tracks de cobertura para visualização
  • Controle de qualidade em múltiplos tipos de dados

Referência: Veja references/common_workflows.md para exemplos detalhados de:

  • Workflows de controle de qualidade (estatísticas BAM, consistência de referência)
  • Análise de cobertura (cobertura por base, detecção de baixa cobertura)
  • Análise de variantes (anotação, filtragem por suporte de leitura)
  • Extração de sequência (contextos de variantes, sequências de genes)
  • Filtragem e subconjuntagem de leituras
  • Padrões de integração (BAM+VCF, VCF+BED, etc.)
  • Otimização de desempenho para workflows complexos

Conceitos-Chave

Sistemas de Coordenadas

Crítico: Pysam usa coordenadas 0-based, meio-abertas (convenção Python):

  • Posições iniciais são 0-based (primeira base é posição 0)
  • Posições finais são exclusivas (não incluídas no intervalo)
  • Região 1000-2000 inclui bases 1000-1999 (1000 bases no total)

Exceção: Strings de região em fetch() seguem convenção samtools (1-based):

samfile.fetch("chr1", 999, 2000)      # 0-based: positions 999-1999
samfile.fetch("chr1:1000-2000")       # 1-based string: positions 1000-2000

Arquivos VCF: Usam coordenadas 1-based no formato de arquivo, mas VariantRecord.start é 0-based.

Requisitos de Indexação

Acesso aleatório a regiões genômicas específicas requer arquivos de índice:

  • Arquivos BAM: Requerem índice .bai (criar com pysam.index())
  • Arquivos CRAM: Requerem índice .crai
  • Arquivos FASTA: Requerem índice .fai (criar com pysam.faidx())
  • Arquivos VCF.gz: Requerem índice tabix .tbi (criar com pysam.tabix_index())
  • Arquivos BCF: Requerem índice .csi

Sem um índice, use fetch(until_eof=True) para leitura sequencial.

Modos de Arquivo

Especifique formato ao abrir arquivos:

  • "rb" - Ler BAM (binário)
  • "r" - Ler SAM (texto)
  • "rc" - Ler CRAM
  • "wb" - Escrever BAM
  • "w" - Escrever SAM
  • "wc" - Escrever CRAM

Considerações de Desempenho

  1. Sempre use arquivos indexados para operações de acesso aleatório
  2. Use pileup() para análise coluna a coluna em vez de operações fetch repetidas
  3. Use count() para contagem em vez de iterar e contar manualmente
  4. Processe regiões em paralelo ao analisar regiões genômicas independentes
  5. Feche arquivos explicitamente para liberar recursos
  6. Use until_eof=True para processamento sequencial sem índice
  7. Evite múltiplos iteradores a menos que necessário (use multiple_iterators=True se necessário)

Armadilhas Comuns

  1. Confusão de coordenadas: Lembre-se dos sistemas 0-based vs 1-based em diferentes contextos
  2. Índices ausentes: Muitas operações requerem arquivos de índice—crie-os primeiro
  3. Sobreposições parciais: fetch() retorna leituras que sobrepõem limites de região, não apenas aquelas totalmente contidas
  4. Escopo do iterador: Mantenha referências do iterador pileup vivas para evitar erro "PileupProxy accessed after iterator finished"
  5. Edição de pontuação de qualidade: Não pode modificar query_qualities no local após alterar query_sequence—crie uma cópia primeiro
  6. Limitações de stream: Apenas stdin/stdout são suportados para streaming, não objetos de arquivo Python arbitrários
  7. Segurança de thread: Enquanto a GIL é liberada durante I/O, a segurança abrangente de thread não foi totalmente validada

Ferramentas de Linha de Comando

Pysam fornece acesso a comandos samtools e 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")

Tratamento de erros:

try:
    pysam.samtools.sort("-o", "output.bam", "input.bam")
except pysam.SamtoolsError as e:
    print(f"Error: {e}")

Recursos

references/

Documentação detalhada para cada capacidade principal:

  • alignment_files.md - Guia completo para operações SAM/BAM/CRAM, incluindo classe AlignmentFile, atributos de AlignedSegment, operações fetch, análise de pileup e escrita de alinhamentos

  • variant_files.md - Guia completo para operações VCF/BCF, incluindo classe VariantFile, atributos de VariantRecord, manejo de genótipo, campos INFO/FORMAT e operações multi-amostra

  • sequence_files.md - Guia completo para operações FASTA/FASTQ, incluindo classes FastaFile e FastxFile, extração de sequência, manejo de pontuação de qualidade e acesso a arquivos indexados por tabix

  • common_workflows.md - Exemplos práticos de workflows bioinformáticos integrados combinando múltiplos tipos de arquivo, incluindo controle de qualidade, análise de cobertura, validação de variantes e extração de sequência

Obtendo Ajuda

Para informações detalhadas sobre operações específicas, consulte o documento de referência apropriado:

  • Trabalhar com arquivos BAM ou calcular cobertura → alignment_files.md
  • Analisar variantes ou genótipos → variant_files.md
  • Extrair sequências ou processar FASTQ → sequence_files.md
  • Workflows complexos integrando múltiplos tipos de arquivo → common_workflows.md

Documentação oficial: https://pysam.readthedocs.io/