1. Take a REST from manual searching: PDBe, programmatically
PDBe.org/API
proteindatabank
@PDBeurope
pdbart
pdbeurope
David Armstrong
Part of EMBL-EBI programmatic access webinar series
See first introductory webinar for basics of programmatic access
Me + John on chat
John Berrisford

2. Summary Introduction to data at the PDBe PDBe’s RESTful API
Finding additional annotation programmatically
Advanced searching programmatically
Simple example script

3. Introduction to PDBe resources

4. Annotation is done geographically – but all into a single archive
Different websites and tools to access this data from each site.
PDBe.org/API

5. The Protein Data Bank (PDB) is an archive of experimentally determined 3-dimensional structures of biological macromolecules
Experimentally determined from 3 main methods: X-ray cryst, NMR and EM
Not just proteins – also nucleic acids
Bear in mind the types of molecules when analyzing data programmatically
Proteins DNA/RNA Complexes of Protein and NA
PDBe.org/API

6. PDB over the years In May 2014, we passed the 100,000 milestone
Very large amounts of data now in the PDB archive
Though only ~40,000 unique macromolecules
Bear in mind the redundancy in the archive when using the API
In May 2014, we passed the 100,000 milestone
As of today, ~130,000 structures
PDBe.org/API

7. At the heart of EMBL-EBI resources
Surrounded by many other biological resources
Work with these to add more functional annotation to our data

8. PDBe’s RESTful API

9. RESTful API for PDBe data
Allows access to vast amounts of PDBe data
Powers the PDBe search and web pages
Will always be well maintained!
Link expand on next slide
PDBe.org/API

10. RESTful API for PDBe data
Allows access to vast amounts of PDBe data
Powers the PDBe search and web pages
Will always be well maintained!
Can access API from homepage, or directly ay PDBe.org/API
PDBe.org/API

11. What can the REST API give you?
Split into 8 groups
These REST calls are based on different subsets of data
These are grouped for ease of use
These are available on the documentation page
Thorough set of example calls
Give URL and output JSON on the page
The data from the API split into 8 groups – for ease of use
Find these on the API documentation page
Each group has interactive example calls on the documentation pages… (feed into next slide)
PDBe.org/API

12. Documentation example
Here’s an example call in the ‘PDB’ group
Can see the URL for the call and a short description
Each of the tabs gives list of example calls for that group
Short description of the results given under API URL
PDBe.org/API

13. Documentation example
Can insert specific PDB ID for the example call
‘Summary’ example for PDB entry information
A box is available to run call for a specific PDB entry
PDBe.org/API

14. Documentation example
Also possible with multiple PDB IDs
Can also give list of multiple PDB entry IDs
Gives results for all entry codes provided
PDBe.org/API

15. Documentation example
Enter PDB ID and click ‘Run call’
PDBe.org/API

16. Documentation example
Returns you the URL for that API call
PDBe.org/API

17. Documentation example
URL contains information about the call
Host address
What API it is
The description of the call
The string given as input
What API: the PDBe API
Description of the call: grouping, entry-based, summary call
String input: in this case the PDB ID
PDBe.org/API

18. Quick Poll
Have you used our API before?

19. Finding Additional annotation

20. Additional annotation at PDBe
Information additional to coordinate data
Includes links to other database
Using SIFTS service
PDBe populates this info on the website through the API
SIFTS service brings together data from a number of resources, based on sequence information.
PDBe.org/API

21. Finding Uniprot mappings for PDB entry
PDBe.org/API

22. Finding Uniprot mappings for PDB entry
PDBe.org/API

23. Finding Uniprot mappings for PDB entry
Results given as JSON
PDB ID top level
Mapping type
Mapping ID
Further description
Range covered by mapping
Further description includes mapping section. Within this…
Range covered by the mapping – from the PDB sequence range to Uniprot range
PDBe.org/API

24. Showing sequence annotation at PDBe.org
Component for displaying sequence annotation
Uses API to get this information
PDBe.org/API

25. Finding validation information for PDB entry
Another example…
Can use the API to get validation metrics for an entry
This example describes outliers for specific residues in entry
*Click for URL expand*
PDBe.org/API

26. Finding validation information for PDB entry
Again, URL contains info about the call – part of the validation grouping
PDBe.org/API

27. Finding validation information for PDB entry
Results given as JSON
PDB ID top level
Results listed by entity
Further listed by individual chain
Models required for NMR entries
Each residue with outliers
The list of outliers
Results for that specific call.
Entity, i.e. distinct macromolecules in entry
Chain – because may be multiple copies of each macromolecule
Models need to be accounted for
List of each residue containing an outlier
List of outliers for that specific residue
PDBe.org/API

28. LiteMol – powered by PDBe REST API
New, lightweight structure viewer at PDBe
Uses API to get structure and annotation data
Including residue-level validation information
An example of how we use this validation information is LiteMol…
API results on the right show how we get the colours
Yellow has single outlier type
Orange has two outlier types
Red has 3 or more
This is then displayed on the structure to indicate validation issues
PDBe.org/API

29. LiteMol – powered by PDBe REST API
New, lightweight structure viewer at PDBe
Uses API to get structure and annotation data
Including residue-level validation information
PDB Component library
Selection of easy to use web components
Many are powered by API
LiteMol is one the web components in the PDB component library
Can easily install these components on your own website
*Next slide for link*
PDBe.org/API

30. LiteMol – powered by PDBe REST API
New, lightweight structure viewer at PDBe
Uses API to get structure and annotation data
Including residue-level validation information
PDB Component library
Selection of easy to use web components
Many are powered by API
Here is the link for the PDB component library at PDBe.org
PDBe.org/API

31. Quick Poll
Were you previously aware you can use PDBe components on your own website?

32. Advanced Search programmatically
This section will cover searching using the API
Enable more complex queries and feed into our other API groups

33. PDBe web search is based on the API
Initial queries typed into autocomplete search bar
Can then refine search by additional queries
These are the facets on the left-hand side
URL contains the queries involved in the search
Directly corresponding to API calls
Before we discuss the search API…
Web search feeds nicely into API search
PDBe.org/API

34. Query = molecule_name:“Dihydrofolate reductase”
Here is an example of a web search
*click when mentioning DHFR*
hydrofolate reductase”
PDBe.org/API

35. Query = molecule_name:“Dihydrofolate reductase”
PDBe.org/API

36. Query = molecule_name:“Dihydrofolate reductase”
Can narrow by additional facets/queries
PDBe.org/API

37. Query = molecule_name:“Dihydrofolate reductase”
hydrofolate reductase”&organism_scientific_name:"Homo sapiens”
PDBe.org/API

38. Query = molecule_name:“Dihydrofolate reductase”
hydrofolate reductase”&organism_scientific_name:"Homo sapiens”
PDBe.org/API

39. Search in the documentation page
Moving on to the API search, using API documentation to demonstrate
Group is ‘Search’ *click*
Also get URL for search API *click*
*Move to next slide for URL description*
PDBe.org/API

40. Search in the documentation page
URL contains information about the call
Host address
Defining PDBe search API
Always “pdb/select?” for search API
The query given as input
PDBe.org/API

41. Search queries in the documentation
List of search queries in documentation, for example…
*click* PDB ID
*click* deposition year
PDBe.org/API

42. Search in the documentation page
Here is the interactive example call for the search documentation
*click* Our search is powered by Solr
*click* Link here to access documentation for building Solr calls
PDBe.org/API

43. Search in the documentation page
Run same example search as in our web search
URL given back
If we look closer *click* can see queries in same format as web search URL *click*
Significant difference *click* is in the linking of multiple queries
Using word AND enables options for OR and NOT as well.
Still ‘&’ to separate different search parameters, e.g. result format
Search API URL differs in linking queries
Uses ‘ AND ’ rather than ‘&’
Otherwise, query terms interchangeable
PDBe.org/API

44. Search in the documentation page
Search results as JSON
Summary in responseHeader
response gives no. of hits
Results found in docs
Given as dictionary
Values for each parameter
ResponseHeader gives status and the search parameters
Parameters show difference in linking types:
Queries contain ‘ AND ‘ while result format, separated in URL by ‘&’ is a separate parameter
Final: for this example, the list of entry authors is shown
PDBe.org/API

45. Simple example script
Shows how to write a basic PDBe API search programmatically to run as a script

46. Simple example script Example Python script requests module for API
Specifying base URLs
Defining search terms
Run search script
Run the API request
Create result list of PDB IDs
Run search using our search terms, with the run_search command defined above
Once returned our result, can extract results from within the response and docs levels
For each result we add the PDB ID to a list - now have output of results as PDB IDs
Can use as input to further API calls
PDBe.org/API

47. Conclusions Large amount of PDB data available
PDBe includes further data from other services
API documentation makes building calls simple
Web search URLs translate to API search
PDBe website powered by API
Means API is up to date and reliable!

48. Thank you for your attention! Any questions?
PDBe.org/API
proteindatabank
@PDBeurope
pdbart
pdbeurope
David Armstrong
Thank you for watching this EBI webinar
Contact info – also API mailing list at URL on slide
John and I still available for questions – use the chat box to ask these.
John Berrisford

49. Next in the series Feedback See the full list of upcoming webinars at
Feedback
Tell us what you think
PDBe.org/API