biopython

Biopython: Biologia Molecular Computacional em Python

Visão Geral

Biopython é um conjunto abrangente de ferramentas Python gratuitas para computação biológica. Ele fornece funcionalidades para manipulação de sequências, E/S de arquivos, acesso a bancos de dados, bioinformática estrutural, filogenética e muitas outras tarefas de bioinformática. A versão atual é Biopython 1.87 (lançada em 30 de março de 2026). Ela suporta Python 3.10-3.14 e PyPy3.10, e requer NumPy. O Biopython 1.87 também aborda a CVE-2025-68463 em Bio.Entrez.Parser ao analisar arquivos não confiáveis, portanto, prefira a versão 1.87+ para fluxos de trabalho que analisam XML do Entrez fornecido externamente.

Quando Usar Este Skill

Use este skill quando:

• Trabalhando com sequências biológicas (DNA, RNA ou proteína)
• Lendo, escrevendo ou convertendo formatos de arquivo biológicos (FASTA, GenBank, FASTQ, PDB, mmCIF, etc.)
• Acessando bancos de dados do NCBI (GenBank, PubMed, Protein, Gene, etc.) via Entrez
• Executando buscas BLAST ou analisando resultados BLAST
• Realizando alinhamentos de sequências (alinhamentos pareados ou múltiplos)
• Analisando estruturas de proteínas a partir de arquivos PDB
• Criando, manipulando ou visualizando árvores filogenéticas
• Encontrando motivos de sequência ou analisando padrões de motivos
• Calculando estatísticas de sequência (conteúdo GC, peso molecular, temperatura de melting, etc.)
• Realizando tarefas de bioinformática estrutural
• Trabalhando com dados de genética de populações
• Qualquer outra tarefa de biologia molecular computacional

Capacidades Principais

Biopython é organizado em subpacotes modulares, cada um abordando domínios específicos da bioinformática:

1. Manipulação de Sequências - Bio.Seq e Bio.SeqIO para manipulação de sequências e E/S de arquivos
2. Análise de Alinhamentos - Bio.Align e Bio.AlignIO para alinhamentos pareados e múltiplos
3. Acesso a Bancos de Dados - Bio.Entrez para acesso programático aos bancos de dados do NCBI
4. Operações BLAST - Bio.Blast para executar e analisar buscas BLAST
5. Bioinformática Estrutural - Bio.PDB para trabalhar com estruturas 3D de proteínas
6. Filogenética - Bio.Phylo para manipulação e visualização de árvores filogenéticas
7. Recursos Avançados - Motivos, genética de populações, utilitários de sequência e muito mais

Instalação e Configuração

Instale a versão estável atual do Biopython com uma fixação explícita de versão para reprodutibilidade:

uv pip install "biopython==1.87"

Para acesso a bancos de dados do NCBI, sempre defina seu endereço de e-mail (exigido pelo NCBI). Para software reutilizável, defina um valor estável para Entrez.tool e registre a ferramenta/e-mail junto ao NCBI. Para limites de taxa mais altos (10 req/s em vez de 3 req/s), leia apenas NCBI_API_KEY do ambiente — não codifique chaves nem carregue variáveis de ambiente não relacionadas:

import os
from Bio import Entrez

Entrez.email = "[email protected]"  # obrigatório — use seu e-mail real
Entrez.tool = "nome_da_sua_ferramenta"  # opcional, mas recomendado para software reutilizável

# Opcional: registre-se em https://www.ncbi.nlm.nih.gov/account/settings/
if api_key := os.environ.get("NCBI_API_KEY"):
    Entrez.api_key = api_key

Usando Este Skill

Este skill fornece documentação abrangente organizada por área de funcionalidade. Ao trabalhar em uma tarefa, consulte a documentação de referência relevante:

1. Manipulação de Sequências (Bio.Seq & Bio.SeqIO)

Referência: references/sequence_io.md

Use para:

• Criar e manipular sequências biológicas
• Ler e escrever arquivos de sequência (FASTA, GenBank, FASTQ, etc.)
• Converter entre formatos de arquivo
• Extrair sequências de arquivos grandes
• Tradução, transcrição e complemento reverso de sequências
• Trabalhar com objetos SeqRecord

Exemplo rápido:

from Bio import SeqIO

# Ler sequências de um arquivo FASTA
for record in SeqIO.parse("sequencias.fasta", "fasta"):
    print(f"{record.id}: {len(record.seq)} pb")

# Converter GenBank para FASTA
SeqIO.convert("entrada.gb", "genbank", "saida.fasta", "fasta")

2. Análise de Alinhamentos (Bio.Align & Bio.AlignIO)

Referência: references/alignment.md

Use para:

• Alinhamento pareado de sequências (global e local)
• Ler e escrever alinhamentos múltiplos de sequências
• Usar matrizes de substituição (BLOSUM, PAM)
• Calcular estatísticas de alinhamento
• Personalizar parâmetros de alinhamento

Exemplo rápido:

from Bio import Align

# Alinhamento pareado
aligner = Align.PairwiseAligner()
aligner.mode = 'global'
alignments = aligner.align("ACCGGT", "ACGGT")
print(alignments[0])

3. Acesso a Bancos de Dados (Bio.Entrez)

Referência: references/databases.md

Use para:

• Pesquisar bancos de dados do NCBI (PubMed, GenBank, Protein, Gene, etc.)
• Baixar sequências e registros
• Obter informações de publicações
• Encontrar registros relacionados entre bancos de dados
• Baixar em lote com limite de taxa adequado

Exemplo rápido:

from Bio import Entrez
Entrez.email = "[email protected]"

# Pesquisar PubMed
handle = Entrez.esearch(db="pubmed", term="biopython", retmax=10)
results = Entrez.read(handle)
handle.close()
print(f"Encontrados {results['Count']} resultados")

4. Operações BLAST (Bio.Blast)

Referência: references/blast.md

Use para:

• Executar buscas BLAST via serviços web do NCBI
• Executar buscas BLAST locais
• Analisar saída BLAST em XML
• Filtrar resultados por E-value ou identidade
• Extrair sequências de hits

Exemplo rápido:

from Bio.Blast import NCBIWWW, NCBIXML

# Executar busca BLAST
result_handle = NCBIWWW.qblast("blastn", "nt", "ATCGATCGATCG")
blast_record = NCBIXML.read(result_handle)

# Exibir principais hits
for alignment in blast_record.alignments[:5]:
    print(f"{alignment.title}: E-value={alignment.hsps[0].expect}")

5. Bioinformática Estrutural (Bio.PDB)

Referência: references/structure.md

Use para:

• Analisar arquivos de estrutura PDB e mmCIF
• Navegar pela hierarquia da estrutura proteica (SMCRA: Structure/Model/Chain/Residue/Atom)
• Calcular distâncias, ângulos e diedros
• Atribuição de estrutura secundária (DSSP)
• Superposição de estruturas e cálculo de RMSD
• Extrair sequências de estruturas

Exemplo rápido:

from Bio.PDB import PDBParser

# Analisar estrutura
parser = PDBParser(QUIET=True)
structure = parser.get_structure("1crn", "1crn.pdb")

# Calcular distância entre carbonos alfa
chain = structure[0]["A"]
distance = chain[10]["CA"] - chain[20]["CA"]
print(f"Distância: {distance:.2f} Å")

6. Filogenética (Bio.Phylo)

Referência: references/phylogenetics.md

Use para:

• Ler e escrever árvores filogenéticas (Newick, NEXUS, phyloXML)
• Construir árvores a partir de matrizes de distância ou alinhamentos
• Manipular árvores (poda, reroot, ladderização)
• Calcular distâncias filogenéticas
• Criar árvores de consenso
• Visualizar árvores

Exemplo rápido:

from Bio import Phylo

# Ler e visualizar árvore
tree = Phylo.read("arvore.nwk", "newick")
Phylo.draw_ascii(tree)

# Calcular distância
distance = tree.distance("Especie_A", "Especie_B")
print(f"Distância: {distance:.3f}")

7. Recursos Avançados

Referência: references/advanced.md

Use para:

• Motivos de sequência (Bio.motifs) - Encontrar e analisar padrões de motivos
• Genética de populações (Bio.PopGen) - Arquivos GenePop, cálculos de Fst, testes de Hardy-Weinberg
• Utilitários de sequência (Bio.SeqUtils) - Conteúdo GC, temperatura de melting, peso molecular, análise de proteínas
• Análise de restrição (Bio.Restriction) - Encontrar sítios de enzimas de restrição
• Clusterização (Bio.Cluster) - K-means e clusterização hierárquica
• Diagramas de genoma (GenomeDiagram) - Visualizar características genômicas

Exemplo rápido:

from Bio.SeqUtils import gc_fraction, molecular_weight
from Bio.Seq import Seq

seq = Seq("ATCGATCGATCG")
print(f"Conteúdo GC: {gc_fraction(seq):.2%}")
print(f"Peso molecular: {molecular_weight(seq, seq_type='DNA'):.2f} g/mol")

Diretrizes Gerais de Fluxo de Trabalho

Lendo Documentação

Quando um usuário perguntar sobre uma tarefa específica do Biopython:

1. Identifique o módulo relevante com base na descrição da tarefa
2. Leia o arquivo de referência apropriado usando a ferramenta Read
3. Extraia padrões de código relevantes e adapte-os às necessidades específicas do usuário
4. Combine vários módulos quando a tarefa exigir

Exemplos de padrões de pesquisa para arquivos de referência:

# Encontrar informações sobre funções específicas
rg -n "SeqIO.parse" references/sequence_io.md

# Encontrar exemplos de tarefas específicas
rg -n "BLAST" references/blast.md

# Encontrar informações sobre conceitos específicos
rg -n "alinhamento" references/alignment.md

Escrevendo Código Biopython

Siga estes princípios ao escrever código Biopython:

1. Importe módulos explicitamente

   from Bio import SeqIO, Entrez
   from Bio.Seq import Seq
   

2. Defina o e-mail do Entrez ao usar bancos de dados do NCBI; carregue apenas NCBI_API_KEY do ambiente, se presente

   import os
   from Bio import Entrez
   
   Entrez.email = "[email protected]"
   Entrez.tool = "nome_da_sua_ferramenta"
   if api_key := os.environ.get("NCBI_API_KEY"):
       Entrez.api_key = api_key
   

3. Use formatos de arquivo apropriados - Verifique qual formato melhor se adequa à tarefa

   # Formatos comuns: "fasta", "genbank", "fastq", "clustal", "phylip"
   

4. Manipule arquivos adequadamente - Feche os handles após o uso ou use gerenciadores de contexto

   with open("arquivo.fasta") as handle:
       records = SeqIO.parse(handle, "fasta")
   

5. Use iteradores para arquivos grandes - Evite carregar tudo na memória

   for record in SeqIO.parse("arquivo_grande.fasta", "fasta"):
       # Processar um registro de cada vez
   

6. Lide com erros graciosamente - Operações de rede e análise de arquivos podem falhar

   from urllib.error import HTTPError
   
   try:
       handle = Entrez.efetch(db="nucleotide", id=accession)
   except HTTPError as e:
       print(f"Erro: {e}")
   

Padrões Comuns

Padrão 1: Obter Sequência do GenBank

from Bio import Entrez, SeqIO

Entrez.email = "[email protected]"

# Obter sequência
handle = Entrez.efetch(db="nucleotide", id="EU490707", rettype="gb", retmode="text")
record = SeqIO.read(handle, "genbank")
handle.close()

print(f"Descrição: {record.description}")
print(f"Tamanho da sequência: {len(record.seq)}")

Padrão 2: Pipeline de Análise de Sequências

from Bio import SeqIO
from Bio.SeqUtils import gc_fraction

for record in SeqIO.parse("sequencias.fasta", "fasta"):
    # Calcular estatísticas
    gc = gc_fraction(record.seq)
    length = len(record.seq)

    # Encontrar ORFs, traduzir, etc.
    protein = record.seq.translate()

    print(f"{record.id}: {length} pb, GC={gc:.2%}")

Padrão 3: BLAST e Obter Principais Hits

from Bio.Blast import NCBIWWW, NCBIXML
from Bio import Entrez, SeqIO

Entrez.email = "[email protected]"

# Executar BLAST
result_handle = NCBIWWW.qblast("blastn", "nt", sequence)
blast_record = NCBIXML.read(result_handle)

# Obter acessos dos principais hits
accessions = [aln.accession for aln in blast_record.alignments[:5]]

# Obter sequências
for acc in accessions:
    handle = Entrez.efetch(db="nucleotide", id=acc, rettype="fasta", retmode="text")
    record = SeqIO.read(handle, "fasta")
    handle.close()
    print(f">{record.description}")

Padrão 4: Construir Árvore Filogenética a Partir de Sequências

from Bio import AlignIO, Phylo
from Bio.Phylo.TreeConstruction import DistanceCalculator, DistanceTreeConstructor

# Ler alinhamento
alignment = AlignIO.read("alinhamento.fasta", "fasta")

# Calcular distâncias
calculator = DistanceCalculator("identity")
dm = calculator.get_distance(alignment)

# Construir árvore
constructor = DistanceTreeConstructor()
tree = constructor.nj(dm)

# Visualizar
Phylo.draw_ascii(tree)

Melhores Práticas

1. Sempre leia a documentação de referência relevante antes de escrever código
2. Use grep para pesquisar arquivos de referência por funções ou exemplos específicos
3. Valide formatos de arquivo antes de analisar
4. Lide com dados ausentes graciosamente - Nem todos os registros têm todos os campos
5. Armazene dados baixados em cache - Não baixe repetidamente as mesmas sequências
6. Respeite os limites de taxa do NCBI - Use chaves de API, valores registrados de ferramenta/e-mail para software reutilizável e histórico/lotes do Entrez para trabalhos grandes
7. Teste com conjuntos de dados pequenos antes de processar arquivos grandes
8. Mantenha o Biopython atualizado para obter os recursos e correções de bugs mais recentes
9. Use tabelas de código genético apropriadas para tradução
10. Documente os parâmetros de análise para reprodutibilidade

Solução de Problemas Comuns

Problema: "No handlers could be found for logger 'Bio.Entrez'"

Solução: Isso é apenas um aviso. Defina Entrez.email para suprimi-lo.

Problema: "HTTP Error 400" do NCBI

Solução: Verifique se os IDs/acessos são válidos e estão formatados corretamente.

Problema: "ValueError: EOF" ao analisar arquivos

Solução: Verifique se o formato do arquivo corresponde à string de formato especificada.

Problema: O alinhamento falha com "sequences are not the same length"

Solução: Garanta que as sequências estejam alinhadas antes de usar AlignIO ou MultipleSeqAlignment.

Problema: As buscas BLAST são lentas

Solução: Use BLAST local para buscas em larga escala ou armazene resultados em cache.

Problema: Avisos do analisador PDB

Solução: Use PDBParser(QUIET=True) para suprimir avisos ou investigue a qualidade da estrutura.

Problema: ImportError para Bio.HMM, Bio.MarkovModel ou Bio.Application

Solução: Esses módulos foram removidos no Biopython 1.86. Use hmmlearn para HMMs e o módulo padrão subprocess em vez dos wrappers de CLI do Bio.Application.

Problema: PairwiseAligner retorna menos alinhamentos após atualizar para 1.86+

Solução: A pontuação de gap padrão mudou de 0 para -1 na versão 1.86, eliminando alinhamentos de empate triviais. Defina aligner.gap_score = 0 para restaurar o comportamento antigo, se necessário (veja references/alignment.md).

Recursos Adicionais

• Documentação Oficial: https://biopython.org/docs/latest/
• Tutorial: https://biopython.org/docs/latest/Tutorial/
• Cookbook: https://biopython.org/docs/latest/Tutorial/ (exemplos avançados)
• GitHub: https://github.com/biopython/biopython
• Registro: https://pypi.org/project/biopython/