UniProt REST API Lesson¶

This notebook shows how to use yanglab.UniProt with the newer UniProt REST endpoint.

We will move through four ideas:

  1. Fetch one UniProt record as raw JSON
  2. Inspect the top-level fields in the response
  3. Parse the record with UniprotRecord

1. Setup¶

We first move into the workshop directory and import the UniProt helpers.

In [1]:
import os
os.chdir('..')

from yanglab.UniProt import queryUniprot, searchUniprot

2. Fetch a UniProt record as raw JSON¶

A good starting point is a UniProt accession. Here we use P04439.

queryUniprot() returns the raw JSON dictionary from the UniProt REST API.

In [7]:
accession = 'P01889'
raw = queryUniprot(accession)
type(raw), raw['primaryAccession']
Out[7]:
(dict, 'P01889')

3. Inspect the shape of the JSON¶

Before parsing deeply, it is always useful to inspect the top-level keys.

In [ ]:
sorted(raw.keys())
Out[ ]:
['annotationScore',
 'comments',
 'entryAudit',
 'entryType',
 'extraAttributes',
 'features',
 'genes',
 'keywords',
 'organism',
 'primaryAccession',
 'proteinDescription',
 'proteinExistence',
 'references',
 'secondaryAccessions',
 'sequence',
 'uniProtKBCrossReferences',
 'uniProtkbId']
In [5]:
raw['proteinDescription']
Out[5]:
{'recommendedName': {'fullName': {'value': 'HLA class I histocompatibility antigen, A alpha chain'}},
 'alternativeNames': [{'fullName': {'value': 'Human leukocyte antigen A'},
   'shortNames': [{'value': 'HLA-A'}]}],
 'flag': 'Precursor'}
In [6]:
raw['organism']
Out[6]:
{'scientificName': 'Homo sapiens',
 'commonName': 'Human',
 'taxonId': 9606,
 'lineage': ['Eukaryota',
  'Metazoa',
  'Chordata',
  'Craniata',
  'Vertebrata',
  'Euteleostomi',
  'Mammalia',
  'Eutheria',
  'Euarchontoglires',
  'Primates',
  'Haplorrhini',
  'Catarrhini',
  'Hominidae',
  'Homo']}

4. Parse the record with UniprotRecord¶

searchUniprot() fetches the record and wraps it inside a UniprotRecord object. This makes the data easier to use through biologically meaningful getter methods.

In [9]:
record = searchUniprot(accession)

@> Parse UniProt information of P01889...
@> Parsing in 0.0s.
In [8]:
record.getOrganism()
Out[8]:
{'scientific_name': 'Homo sapiens',
 'common_name': 'Human',
 'taxonomy_id': 9606,
 'lineage': ['Eukaryota',
  'Metazoa',
  'Chordata',
  'Craniata',
  'Vertebrata',
  'Euteleostomi',
  'Mammalia',
  'Eutheria',
  'Euarchontoglires',
  'Primates',
  'Haplorrhini',
  'Catarrhini',
  'Hominidae',
  'Homo']}

5. Basic biological fields¶

These are usually the first fields we want from UniProt.

In [ ]:
record.getAccession()
Out[ ]:
'P04439'
In [ ]:
record.getName()
Out[ ]:
'HLAA_HUMAN'
In [ ]:
record.getProtein()
Out[ ]:
{'recommend_name': 'HLA class I histocompatibility antigen, A alpha chain',
 'alter_fullname': 'Human leukocyte antigen A',
 'alter_shortname': 'HLA-A'}
In [ ]:
record.getGene()
Out[ ]:
'HLA-A'
In [ ]:
record.getOrganism()
Out[ ]:
{'scientific_name': 'Homo sapiens',
 'common_name': 'Human',
 'taxonomy_id': 9606,
 'lineage': ['Eukaryota',
  'Metazoa',
  'Chordata',
  'Craniata',
  'Vertebrata',
  'Euteleostomi',
  'Mammalia',
  'Eutheria',
  'Euarchontoglires',
  'Primates',
  'Haplorrhini',
  'Catarrhini',
  'Hominidae',
  'Homo']}
In [ ]:
sequence = record.getSequence()
len(sequence), sequence[:60]
Out[ ]:
(365, 'MAVMAPRTLLLLLSGALALTQTWAGSHSMRYFFTSVSRPGRGEPRFIAVGYVDDTQFVRF')

6. Features and comments¶

UniProt records contain two very important blocks:

  • features: positional annotations on the sequence
  • comments: descriptive annotations such as subunit, PTM, and interactions
In [ ]:
len(record.getFeatures()), len(record.getComments())
Out[ ]:
(162, 33)
In [5]:
comments = record.getComments()
In [4]:
record.getAPIURL(), record.getFamilyDomains()
Out[4]:
('https://rest.uniprot.org/uniprotkb/P61769',
 [{'type': 'Domain',
   'description': 'Ig-like C1-type',
   'begin': 25,
   'end': 113}])
In [16]:
record.getBindingSite()[:3]
Out[16]:
[{'position': 31,
  'description': '',
  'name': 'a peptide antigen',
  'chebi': 'CHEBI:166823'},
 {'position': 97,
  'description': '',
  'name': 'a peptide antigen',
  'chebi': 'CHEBI:166823'},
 {'position': 108,
  'description': '',
  'name': 'a peptide antigen',
  'chebi': 'CHEBI:166823'}]
In [17]:
record.getActiveSite()[:3]
Out[17]:
[]
In [11]:
record.getPTMProcessing()
Out[11]:
[{'type': 'Signal', 'begin': 1, 'end': 24, 'description': ''},
 {'type': 'Chain',
  'begin': 25,
  'end': 362,
  'description': 'HLA class I histocompatibility antigen, B alpha chain'},
 {'type': 'Glycosylation',
  'position': 110,
  'description': 'N-linked (GlcNAc...) asparagine'},
 {'type': 'Disulfide bond', 'begin': 125, 'end': 188, 'description': ''},
 {'type': 'Disulfide bond', 'begin': 227, 'end': 283, 'description': ''}]
In [19]:
record.getSubunit('all')[:3]
Out[19]:
['Heterotrimer that consists of an alpha chain HLA-A, a beta chain B2M and a peptide (peptide-HLA-A-B2M) (PubMed:11502003, PubMed:18275829, PubMed:19177349, PubMed:19542454, PubMed:21943705, PubMed:22245737, PubMed:24395804, PubMed:26758806, PubMed:28250417, PubMed:7504010, PubMed:7506728, PubMed:7679507, PubMed:7694806, PubMed:7935798, PubMed:8805302, PubMed:8906788, PubMed:9177355). Early in biogenesis, HLA-A-B2M dimer interacts with the components of the peptide-loading complex composed of TAPBP, TAP1-TAP2, TAPBPL, PDIA3/ERP57 and CALR (PubMed:21263072). Interacts with TAP1-TAP2 transporter via TAPBP; this interaction is obligatory for the loading of peptide epitopes delivered to the ER by TAP1-TAP2 transporter (PubMed:21263072, PubMed:8630735, PubMed:8805302). Interacts with TAPBPL; TAPBPL binds peptide-free HLA-A-B2M complexes or those loaded with low affinity peptides, likely facilitating peptide exchange for higher affinity peptides (PubMed:26869717, PubMed:35725941). Only optimally assembled peptide-HLA-B2M trimer translocates to the surface of antigen-presenting cells, where it interacts with TCR and CD8 coreceptor on the surface of T cells. HLA-A (via polymorphic alpha-1 and alpha-2 domains) interacts with antigen-specific TCR (via CDR3 domains) (PubMed:12796775, PubMed:18275829, PubMed:22245737). One HLA-A molecule (mainly via nonpolymorphic alpha-3 domain) interacts with one CD8A homodimer (via CDR-like loop); this interaction ensures peptide-HLA-A-B2M recognition by CD8-positive T cells only (PubMed:2784196, PubMed:9177355). Alleles A*23:01; A*24:02 and A*32:01 interact (via Bw4 motif) with KIR3DL1 on NK cells; this interaction is direct',
 '(Microbial infection) Interacts with HHV-8 MIR1 protein',
 '(Microbial infection) Interacts with HTLV-1 accessory protein p12I']

7. Cross-references to other databases¶

UniProt links one protein record to many other resources. These are available through cross-references.

In [20]:
sorted(record.getCrossReferences().keys())[:20]
Out[20]:
['ABCD',
 'AGR',
 'Agora',
 'AlphaFoldDB',
 'Antibodypedia',
 'Bgee',
 'BindingDB',
 'BioGRID',
 'BioGRID-ORCS',
 'BioMuta',
 'CCDS',
 'CDD',
 'CIViC',
 'CPTC',
 'CTD',
 'ChEMBL',
 'ChiTaRS',
 'ClinPGx',
 'ComplexPortal',
 'DMDM']
In [21]:
record.getAlphaFold()
Out[21]:
'P04439'
In [22]:
record.getComplexPortals()
Out[22]:
[{'id': 'CPX-26559', 'name': 'Classical MHC Ia complex, HLA-A-B2M'}]
In [23]:
list(record.getPDBs().items())[:3]
Out[23]:
[('1AKJ',
  {'method': 'X-ray',
   'resolution': 2.65,
   'chains': ['A'],
   'resrange': '25-300'}),
 ('1AO7',
  {'method': 'X-ray',
   'resolution': 2.6,
   'chains': ['A'],
   'resrange': '25-299'}),
 ('1AQD',
  {'method': 'X-ray',
   'resolution': 2.45,
   'chains': ['C', 'F', 'I', 'L'],
   'resrange': '127-141'})]

8. Keywords and references¶

These are useful for getting a compact summary of function and literature.

In [24]:
record.getKeywords()[:10]
Out[24]:
['3D-structure',
 'Adaptive immunity',
 'Alternative splicing',
 'Cell membrane',
 'Direct protein sequencing',
 'Disulfide bond',
 'Endoplasmic reticulum',
 'Glycoprotein',
 'Host-virus interaction',
 'Immunity']
In [25]:
record.getReferences()[:2]
Out[25]:
[{'id': None,
  'type': 'journal article',
  'title': 'The primary structure of HLA-A32 suggests a region involved in formation of the Bw4/Bw6 epitopes.',
  'journal': 'J. Immunol.',
  'volume': '137',
  'first_page': '3671',
  'last_page': '3674',
  'year': '1986',
  'authors': ['Wan A.M.', 'Ennis P.', 'Parham P.', 'Holmes N.']},
 {'id': None,
  'type': 'journal article',
  'title': 'Multiple genetic mechanisms have contributed to the generation of the HLA-A2/A28 family of class I MHC molecules.',
  'journal': 'J. Immunol.',
  'volume': '139',
  'first_page': '936',
  'last_page': '941',
  'year': '1987',
  'authors': ['Holmes N.',
   'Ennis P.',
   'Wan A.M.',
   'Denney D.W.',
   'Parham P.']}]

9. Teaching takeaway¶

The main workflow is:

  1. fetch the UniProt REST JSON
  2. inspect the response structure
  3. parse it into a Python object
  4. extract the biological fields you care about