pysam

Visão Geral

Use o pysam para acesso de baixo nível e em streaming a formatos genômicos suportados pelo HTSlib:

• AlignmentFile e AlignedSegment para SAM/BAM/CRAM
• VariantFile, VariantHeader e VariantRecord para VCF/BCF
• FastaFile para FASTA indexado e FastxFile para FASTA/FASTQ sequencial
• TabixFile para tabelas BED/GFF/GTF/personalizadas comprimidas com BGZF e indexadas com tabix
• pysam.samtools e pysam.bcftools para despachantes de comandos encapsulados

Linha de base upstream atual: pysam 0.24.1 (7 de setembro de 2026), encapsulando HTSlib/samtools/bcftools 1.24. Leia references/sources.md antes de atualizar orientações específicas de versão.

Instalação

Use a versão fixada para trabalho reproduzível:

uv pip install "pysam==0.24.1"

Confirme o tempo de execução:

import pysam

print(pysam.__version__)           # 0.24.1
print(pysam.__samtools_version__)  # 1.24

Rodas pré-compiladas estão disponíveis para plataformas macOS e Linux suportadas. Uma compilação a partir do código fonte precisa de um compilador C e dependências de compilação do HTSlib; leia o guia oficial de instalação vinculado em references/sources.md.

Decida Primeiro

Antes de escrever código:

1. Identifique o formato real, compressão, ordem de classificação e índice disponível.
2. Decida se as coordenadas são coordenadas numéricas do Python ou uma string de região. Não as misture.
3. Para CRAM, identifique a montagem de referência exata e o FASTA.
4. Prefira acesso a regiões indexadas; use iteração sequencial apenas quando pretendido.
5. Preserve cabeçalhos ao escrever e escreva em um novo caminho por padrão.
6. Declare a semântica de filtragem: qualidade de mapeamento/base, flags, tratamento de sobreposição, tratamento de duplicatas e limite de profundidade de pileup.

Para arquivos desconhecidos, comece com o inspetor somente leitura incluído:

python scripts/inspect_hts.py sample.bam
python scripts/inspect_hts.py cohort.vcf.gz
python scripts/inspect_hts.py reference.fa

Scripts Incluídos

Todos os scripts recusam sobrescrever saídas existentes. O filtro também recusa índices de saída obsoletos e oferece --index --csi para contigs BAM grandes. A inspeção FASTA requer um .fai existente; crie-o explicitamente com pysam.faidx() primeiro. Execute cada um com --help para notas sobre coordenadas, índice e privacidade.

Exemplos usam nomes de arquivo ilustrativos e limiares específicos do ensaio. O conjunto sintético local exercita esses padrões de API no pysam 0.24.1; armazenamento remoto e conjuntos de dados biológicos não fazem parte dessa validação.

Contrato de Coordenadas

Coordenadas numéricas aceitas pelas APIs do pysam são baseadas em 0, meio-abertas. Isso inclui argumentos numéricos AlignmentFile.fetch(), VariantFile.fetch(), FastaFile.fetch(), TabixFile.fetch() e pileup().

Strings de região são no estilo samtools: baseadas em 1 e inclusivas.

# The same 100 bases:
bam.fetch("chr1", 99, 199)          # [99, 199)
bam.fetch(region="chr1:100-199")    # 1-based inclusive

O texto VCF usa POS baseado em 1, enquanto as propriedades do registro expõem ambos os sistemas:

record.pos    # 1-based
record.start  # 0-based inclusive
record.stop   # 0-based exclusive

Leia references/coordinates_and_indexing.md para conversões de formato, semântica de sobreposição, escolhas de índice e verificações de nome de contig.

Arquivos de Alinhamento

Use gerenciadores de contexto e modos explícitos:

import pysam

with pysam.AlignmentFile("sample.bam", "rb", threads=4) as bam:
    for read in bam.fetch("chr1", 1_000, 2_000):
        if (
            not read.is_unmapped
            and not read.is_secondary
            and not read.is_supplementary
            and read.mapping_quality >= 30
        ):
            print(read.query_name, read.reference_start, read.cigarstring)

Use fetch(until_eof=True) para transmitir todos os registros na ordem do arquivo, incluindo leituras não posicionadas e não mapeadas, sem exigir um índice:

with pysam.AlignmentFile("sample.bam", "rb") as bam:

…