BioServices

Quando usar

Use BioServices ao combinar anotações de proteínas, associação a genes/vias, referências cruzadas de compostos ou recursos genômicos em Python. Seus clientes de serviço compartilham utilitários de transporte, mas seus parâmetros de requisição e tipos de retorno diferem. Use a referência de serviços antes de compor clientes; nomes de métodos do PubChemPy, mygene ou versões anteriores do BioServices não são portáteis.

O foco é bioservices 1.16.0, a versão atual do PyPI na data da revisão. Metadados do pacote permitem Python >=3.9,<4; os testes incluídos foram executados em um ambiente Python 3.13 isolado. O limite superior anterior de 3.12 não era um requisito do pacote.

uv pip install "bioservices==1.16.0"

Fluxo de trabalho

1. Resolva o organismo e a entidade solicitados para acessos estáveis. Revise os resultados da busca antes de selecionar um; símbolos de genes e nomes de compostos podem ser ambíguos.
2. Inspecione o tipo de resposta real do serviço, incluindo paginação e erros. BioServices pode retornar um erro HTTP semelhante a um inteiro ou None, não apenas lançar uma exceção.
3. Preserve mapeamentos de um para muitos, identificadores falhos, taxonomia, versão do banco de dados, parâmetros de consulta e data de recuperação ao lado de tabelas derivadas.
4. Distinga anotações e associações inferidas de evidências experimentais. A associação a vias sozinha não é uma análise de enriquecimento ou uma descoberta causal.
5. Execute uma pequena consulta de verificação antes de processar em lote; respeite os limites do provedor e retenha falhas separadamente de resultados confirmados como vazios.

Busca de proteínas, recuperação de sequência e mapeamento

from bioservices import UniProt

u = UniProt(verbose=False)
u.services.TIMEOUT = 30
rows = u.search(
    "gene_exact:ZAP70 AND organism_id:9606 AND reviewed:true",
    frmt="tsv", columns="accession,gene_names,organism_name,length",
    limit=5, size=5,
)
if not isinstance(rows, str):
    raise RuntimeError("UniProt search failed")
print(rows)
fasta = u.retrieve("P43403", frmt="fasta")
record = u.retrieve("P43403", frmt="json")

mapping = u.mapping(fr="UniProtKB_AC-ID", to="KEGG", query="P43403")
if not isinstance(mapping, dict) or "results" not in mapping:
    raise RuntimeError("Mapping incomplete or failed")
kegg_ids = [row["to"] for row in mapping["results"] if row["from"] == "P43403"]
print(kegg_ids, mapping.get("failedIds", []))

Use frmt="tsv", não "tab"; nomes de campos atuais incluem accession, gene_names, organism_name, protein_name, go_id e xref_pdb. mapping() retorna um envelope results/failedIds, não um dicionário de origem para lista. Mapear para UniProt usa to="UniProtKB" e retorna registros completos em row["to"]; extraia primaryAccession. UniProtKB_AC-ID é um código fonte. Veja mapeamento de identificadores para pares permitidos, normalização e limites. Para buscas limitadas, defina size=limit (no máximo 500); 1.16.0 mistura os dois valores em seu loop de paginação.

Vias e redes KEGG

from bioservices import KEGG

k = KEGG(verbose=False)
k.services.url = "https://rest.kegg.jp"
pathway_names = k.get_pathway_by_gene("7535", "hsa")  # dict: pathway ID -> name
print(pathway_names)
kgml = k.parse_kgml_pathway("hsa04660")
entries = {entry["id"]: entry for entry in kgml["entries"]}
for relation in kgml["relations"][:5]:
    print(entries[relation["entry1"]]["name"], relation["name"],
          entries[relation["entry2"]]["name"])

O endpoint /list/organism revisado retornou HTTP 400, apesar de ainda estar no manual. Métodos SDK que validam contra esse catálogo podem falhar. Os scripts incluídos de lista de compostos e vias usam os endpoints com escopo documentados através de k.services.http_get para evitar essa dependência de catálogo não relacionada.

KEGG get permite no máximo dez entradas; KGML permite uma via por requisição. Mantenha as requisições em três por segundo ou menos. list/find retornam strings TSV; get retorna uma string de arquivo plano, a menos que uma opção altere a representação. Entradas KGML incluem genes, compostos, grupos e mapas. Uma relação pode produzir vários registros de subtipo; essas contagens não são genes únicos nem interações físicas independentes. IDs de entrada são locais para cada via. A exportação SIF incluída os nomeia como pathway#entry, portanto, combinar vias não pode mesclar nós não relacionados. pathway2sif(..., uniprot=False) é uma projeção opcional e com perda de dados de ativação/inibição gene-a-gene, não uma rede de via completa.

Referências cruzadas de compostos

from bioservices import UniChem

uc = UniChem(verbose=False)

…