Introducció

UniProt (Universal Protein Resource) és una base de dades de seqüències de proteïnes i la seva corresponent informació funcional. És de lliure accés i conté moltes entrades derivades de projectes de seqüenciació de genomes. Conté al voltant de 60 milions de seqüències de proteïnes, derivada de la literatura científica, sobre la funció biològica de les proteïnes, la qual s’actualitza a mesura que es genera més coneixement

Uniprot neix del consorci UniProt que està format per EBI (European Bioinformatic Institute), SIB (Swiss Institute of Bioinformatics, que té una base de dades anomenada Swiss-prot), organitzacions bioinformàtiques europees i PIR (Protein Information Resource) organització americana de dades de proteïnes.

UniProt ofereix accés a quatre bases de dades de proteïnes:

  1. The UniProt Knowledgebase (UniProtKB),
  2. The UniProt Reference Clusters (UniRef),
  3. The UniProt Metagenomics
  4. Environmental Sequences database Ves a la pàgina web i mira tota la informació que tens disponible: https://www.uniprot.org/

REST API

UniProt proporciona diverses interfícies de programació d'aplicacions (API) per consultar i accedir a les seves dades mitjançant programes.. UniProt website REST API proporciona URLs RESTful que es poden marcar, enllaçar i utilitzar en programes per a totes les entrades, consultes i eines disponibles a través d'aquest lloc web. Les dades estan disponibles en tots els formats proporcionats al lloc web, per exemple text, XML, RDF, FASTA, GFF o TSV per a dades de proteïnes UniProtKB.

Obtenir un recurs

L'adreça web d'una entrada consta d'un nom de conjunt de dades (per exemple, uniprot, uniref, uniparc, taxonomy,...) i l'identificador únic de l'entrada, per exemple:

Per defecte, es retorna una pàgina web.

Depenent del conjunt de dades, també poden estar disponibles altres formats (fes clic a "Download" a la pàgina web de l'entrada).

A continuació tens alguns exemples de consultes HTTP amb httpie:

$ http -p b https://rest.uniprot.org/uniprotkb/P12345.json
...

La resposta és molt llarga per lo que pots guardar la resposta en un fitxer:

$ http -p b https://rest.uniprot.org/uniprotkb/P12345.json > data/P12345.json

I ja pots accedir a la informació del fitxer:

$ less data/P12345.json

Si coneixes l’estructura del document pots accedir directament a la informació que vols, per exemple la seqüència d’aminoàcids.

Instal.la l’eina jq:

$ sudo apt install -y jq

I fes la consulta:

$ http https://rest.uniprot.org/uniprotkb/P12345.json | jq ".sequence"
...

Pots veure com és de fàcil accedir a la informació.

Si només vols la informació de las seqüència pots demanar el resultat en un fitxer FASTA:

$ http -p b https://rest.uniprot.org/uniref/UniRef90_P99999.fasta

Aquest cop fem servir el conjunt de dades uniref, enlloc de uniprokb, i un identificador UniRef.

Has de tenir en compte que no es pot garantir que els identificadors UniRef siguin estables, ja que els clusters de seqüències es tornen a calcular a cada “release” i la proteïna representativa pot canviar.

En aquest document t’expliquen com has de crear els “links” a les entrades UniProt: How to link to UniProt entries (UniProtKB, UniParc and UniRef)

Query

Pots utilitzar qualsevol consulta per definir el conjunt d'entrades que t’interessen.

Al principi pot ser més senzill començar amb una cerca de text interactiva al lloc web per trobar l'URL del teu conjunt.

Per exemple, aquest enllaç et mostra totes les entrades de proteïnes humanes que han estat revisades:

Link

Les dades del lloc web les proporciona l’API REST.

Per a l'exemple anterior, la sol·licitud per recuperar el primer lot de dades seria:

$ http "https://rest.uniprot.org/uniprotkb/search?query=(reviewed:true)%20AND%20(organism_id:9606)" > data/organism_9696.json

Una consulta no retorna tots els resultats possibles sinó un subconjunt d’aquells més rellevants.

Com que has guarda les dades en el fitxer data/organism_9696.json pots consultar el fitxer de dades directament:

$ cat data/organism_9696.json | jq ".results[0].organism.commonName"

Formats

Per demanar un format concret de dades ho pots fer de diverse maneres.

Paràmetre formats

Totes les peticions permeten el paràmetre format, que es pot utilitzar per indicar el format desitjat.

Per exemple, si vull les dades en format tsv:

$ curl -s "https://rest.uniprot.org/uniprotkb/search?query=reviewed:true+AND+organism_id:9606&format=tsv" > data/organism_9696.tsv

El format TSV és molt útil extreure informació de dades “tabulars”:

$ cut -f 1,2 data/organims_9696.tsv | column -t | head -n 10

També pots treballar amb les dades TSV amb Python:

import csv

with open("data/organims_9696.tsv") as file:
    reader = csv.DictReader(file, dialect="excel-tab")
    for i, row in enumerate(reader):
        if (i > 10): break
        print(f"{row['Entry']}\t{row['Entry Name']}")

Pots veure que el resultat és el mateix:

TODO

####Accept Header

Com és habitual amb les sol·licituds REST, el format desitjat es pot especificar com a capçalera Accept.

Per exemple:

$ http -p b https://rest.uniprot.org/uniprotkb/P12345 Accept:"text/plain;format=fasta"
...

Quins formats hi ha disponibles?

Els diferents “end-points” de l’API UniProt proporcionen formats diferents, tot i que, en general, els formats JSON i els valors separats per tabulacions (TSV) estan disponibles en tots els “end-points”.

Description Accept Format
JavaScript Object Notation (JSON) application/json json
Extensible Markup Language (XML) application/xml xml
Text file representation text/plain;format=flatfile txt
List of one or more IDs text/plain;format=list list
Tab-Separated-Values text/plain;format=tsv tsv
FASTA text/plain;format=fasta fasta
Genomic Feature Format (GFF) text/plain;format=gff gff
Open Biomedical Ontologies (OBO) text/plain;format=obo obo
Resource Description Framework (RDF) application/rdf+xml rdf
Excel application/vnd.ms-excel xlsx

Tips

TODO urls

  • Familiaritza’t amb el advanced search builder fent clic a Advanced.

  • Fes clic a Customize data a la pàgina de resultats de la cerca per seleccionar les columnes que es mostraran a la taula de resultats.

  • També pots cercar els noms de columnes rellevants a la llista completa de UniProtKB column names for programmatic access.

  • Alguns d’aquests formats els pots emmagatzemar en Dataframes.

L'URL del resultat d'una consulta consta d'un nom de conjunt de dades (p. ex., uniprot, uniref, uniparc, taxonomia,...) i la consulta real. S'admeten els paràmetres de consulta següents:

TODO urls

Parameter Values Description
query string See query syntax and query fields for UniProtKB.
An empty query string will retrieve all entries in a data set. Tip: Refine your search by clicking Advanced in the search bar.
format See section, "What formats are available?"
fields comma-separated list of column names Columns to retrieve in the results. Applies to tsv, xslx and json formats only. (For UniProtKB you can also read the full list of UniProtKB column names).
includeIsoform true or false Whether or not to include isoforms in the search results. Note: Only applies to UniProtKB searches.
compressed true or false Return results gzipped. Note that if the client supports HTTP compression, results may be compressed transparently even if this parameter is not set to true.
size integer Maximum number of results to retrieve. Note: Only takes effect on searches.
cursor string Specifies the cursor position in the entire result set, from which returned results will begin. Cursors are used to allow paging through results. Typically used together with the size parameter.

L'exemple següent recupera totes les entrades humanes que coincideixen amb el terme "antigen" en formats TSV comprimit:

$ curl -s "https://rest.uniprot.org/uniprotkb/search?query=reviewed:true+AND+organism_id:9606&format=tsv&compressed=true" > data/organism_9696.tsv.gz
...

Com que les dades estan comprimides no les pots utilitzar directament. Primer les has de descomprimir:

També pots fer la consulta avançada; però és més lent.

El següent exemple recupera totes les entrades humanes amb referències creuades a PDB en format separat per tabulacions, mostrant només els identificadors UniProtKB i PDB.

$ http -p b "https://rest.uniprot.org/uniprotkb/search?query=organism_id:9606+AND+database:pdb&format=tsv&fields=id,xref_pdb" | head -n 5
...

El Protein Data Bank (PDB) és l’altre gran base de dades de proteïnes que veurem més endavant

Stream

Si volem que l’API ens torni tots els resultats d’una consulta podem utilitzar l’API stream, encara que només tenim que fer-ho si esperem un nombre “petit” de resultats.

L’objectiu és descarregar les entrades revisades de l'organisme SARS-CoV-2 a UniProtKB.

Farem servir l'”streaming endpoint” que retorna un únic string amb totes les seqüències FASTA.

Per trobar l’entrada de l’organisme has de crear una llista de seqüències FASTA i trobar totes les seqüències que a la capçalera fagin menció a SPIKE:

ìmport re
import urllib.parse
import urllib3

parameters = "format=fasta&query=(organism_id:2697049) AND (reviewed:true)"

#####

parameters = urllib.parse.quote(parameters, safe='=&')
url = f"https://rest.uniprot.org/uniprotkb/stream?{parameters}"
response = urllib3.request("GET", url)
fastas = response.data.decode("utf-8")

# Create a list of FASTA sequences
fastas = re.split(r'\n(?=>)', fastas)
# Find all sequences with header mentioning SPIKE
fastas = [fasta for fasta in fastas if 'SPIKE' in fasta]

print(fastas)

Aquí tens el resultat de la cerca:

Si la vols guardar:

f = open("fastas.fasta", "w")
for fasta in fastas:
    f.write(fasta)
f.close()

Limitacions

El “stream endpoint” suposa molta càrrega de processament a l’API i per aquest motiu hi ha una limitació en el nombre de sol·licituds paral·leles que gestiona.

En el cas que l'stream API tingui massa sol·licituds, la sol.licitut HTTP pot retorna un estat 429.

Si això passa pots utilitzar la paginació (que veurem a continuació) o tornar a provar més tard.

El “stream endpoint” pot gestionar conjunts de resultats de com a màxim de 10.000.000 d'entrades.

Si necessites un conjunt més gran de dades pots descarregar els fitxers FTP: https://ftp.uniprot.org/pub/databases/uniprot/.

query (pagination)

Quan el resultat de la resposta és un gran nombre de resultats, és millor utilitzar la paginació, que vol dir obtenir els resultats d’un en un.

És preferible al streaming perquè:

  1. Menor ús de la memòria. Si les dades dels resultats de la cerca superen la memòria de l'ordinador, la descàrrega mitjançant streaming farà que el script de Python es bloquegi.

    La paginació només carrega un subconjunt dels resultats a la memòria a la vegada.

  2. L’aplicació és més robusta davant problemes de connexió. Si durant una descàrrega per streaming la connexió s'interromp, la descàrrega s'haurà de reiniciar des del principi.

    Quan es treballa amb la paginació, es pot tornar a provar cada lot des del punt de fallada sense necessitat de reiniciar tot el procés.

  3. Menys demanda de recursos a l’API. El “stream endpoint” requereix una gran quantitat de memòria.

    El “pagination endpoint” distribueix la demanda de recursos durant un període de temps més llarg, de manera que la infraestructura de l'API ho pot gestionar millor.

  4. Pots processar cada lot a mesura que arriba. La descàrrega per streaming requereix que la descàrrega s'hagi completat abans que es pugui processar.

    El processament per lots permet intercalar el processament amb la descàrrega, cosa que pot ser útil si es vol veure els resultats processats el més aviat possible.

Aquí tens un diagrama que mostra les diferències:

Stream             Pagination
+------------+     +------------+
| Download 1 |     | Download 1 |
| Download 2 |     | Process  1 |
| Download 3 |     | Download 2 |
| Process  1 |     | Process  2 |
| Process  2 |     | Download 3 |
| Process  3 |     | Process  3 |
+------------+     +------------+

search behaviour is designed to return results in batches (pages), i.e., those that are more relevant to the user's query coming in earlier batches. In addition to these results, a set of HTTP headers are returned, one of which is a special 'Link' TODO:url header, that tells us where to find the next page of results.

Capçaleres de la resposta

Quan fas una consulta(“query endpoint”) l’API està dissenyada per retornar els resultats en lots (pàgines) amb els resultats més rellevants de la consulta en els primers lots.

Ademés del resultat de les dades del lot, en la capçaleres HTTP de la resposta tens una capçalera link que indica on trobar la següent pàgina de resultats:

curl -sI "https://rest.uniprot.org/uniprotkb/search?query=human%20cdc7" | grep ^link
...

També pots veure que la URL es construeix perquè torni 25 resultats per lot (size=25) si en la sol.licitut HTTP no has indicat un valor específic amb l’argument size.

Aquest procediment és semblant al que es fa TODO a BIO-UF2-5 - Entrez amb Biopython i el History Server, però molt més senzill ja que la resposta ja inclou montada la propera URL que has d’utilitzar.

Una altra capçalera rellevant és el nombre de resultats de la resposta:

$ curl -sI "https://rest.uniprot.org/uniprotkb/search?query=human%20cdc7" | grep x-total-results
...

Python

A continuació tenim un programa que busca totes les entrades (articles) revisades que contenen la paraula insulina, ordenades pel nombre més gran d'interaccions.

Pots veure que el programa va fent peticions HTTP (amb una lògica de Retry) fins que arriba una resposta sense la capçalera Link.

També pots veure que com a paràmetre passem el valor size=500 que és el valor màxim admés.

Per obtenir el next link busquem la capçalera Link, i si la trobem, fem servir una expressió regular per extreure la URL:

TODO codi

A continuació tens el resultat d’executar el programa:

Guardar fitxers

La lògica de guardar fitxers és molt senzilla a partir dels programes anteriors.

stream

urllib3 està preparada per treballar amb streams.

A mida que van arribant bytes d’informació l’anem processat en blocs de 1024 bytes escrivint al fitxer corresponent:

query

unipressed

Com que l’API es pot utilitzar amb qualsevol llenguatge de programació és habitual que es vagin creant llibreries per facilitar la interacció amb l’API.

TODO url

L’última llibreria en Python és aquesta: GitHub - multimeric/Unipressed: Comprehensive Python client for the Uniprot REST API

nodejs

Com passava amb la base de dades Entrez, també pots interactuar directament amb la Uniprot mitjançant Javascript.

Com que es tracta d’una API REST pots utilitzar una llibreria de client REST.

https://www.npmjs.com/package/node-rest-client