Get an association table for your list of genes
Many users look at our table view, showing which genes are associated to a specific disease:
However, they sometimes want to restrict this view to a list of genes they are interested in, either because they have already focussed their attention on a specific set of targets or because these targets surface in a different experiment.
Good news: our API makes this easy. One can obtain all the data behind the table view using the API and specifically the /public/association/filter call.
Get the data
For instance, to select data for the first 10 targets associated with a particular disease (eg. asthma) we can use the disease parameter with the EFO code (for asthma that is EFO_0000270) and add it at the end of the URL:
https://api.opentargets.io/v3/platform/public/association/filter?disease=EFO_0000270
Clicking on the link in your browser, will show a very unfriendly JSON dump of our data:
You can make this view much prettier and user-friendly by installing a browser extension (there are many available for Chrome, Safari and Firefox):
Otherwise, you can download the same data as a tab separated file, by adding the format=tab parameter at the end of the same URL. Notice how each parameter is separated from the previous one by an &:
https://api.opentargets.io/v3/platform/public/association/filter?disease=EFO_0000270&format=tab
Different formats can be obtained using format=tab, format=csv and format=xml.
There is also the possibility of adding a datastructure=simple option at the end of the URL, which gives a simplified structure ready to be placed in a spreadsheet:
https://api.opentargets.io/v3/platform/public/association/filter?disease=EFO_0000270&datastructure=simple
You can download the same view as a csv file and open it in your spreadsheet editor.
Select the fields you are interested in
If we want to select particular fields, say the overall association score, we can add the fields parameter at the end of the URL:
A list of scores is hardly useful without a description of which target and disease they are linking. We can select more data by using the parameter fields for every item we want to get:
https://api.opentargets.io/v3/platform/public/association/filter?disease=EFO_0000270&fields=association_score.overall&fields=target.id&fields=disease.id
I only want my targets!
That is all well and good, but what we are really after is a way to get the data only for a few particular genes. Adding a target= parameter to the end of the URL solves the problem:
Notice that the target ID needs to be in the ENSGXXXXXXXXXXX IDs format. To convert your IDs to ENSG IDs, you can use our API as described in a previous post.
We can use the target parameters multiple times, until we get all the genes we are looking for:
https://api.opentargets.io/v3/platform/public/association/filter?disease=EFO\_0000270&fields=association_score.overall&fields=target.id in addition to
`&target=ENSG00000073756&target=ENSG00000172057&target=ENSG00000205189`
If you have too many targets to do this, the same API endpoint accepts POST methods. You need to first save a file in JSON format. For the call above it would be:
{"disease"="EFO_0000270", "target"=["ENSG00000073756","ENSG00000172057","ENSG00000205189"], "fields"=["association_score.overall","target.id","disease.id"], "format"="tab" }And from the command line you can use curl to send a POST request and get a tab separated file back:
curl -X POST -d @myjsonfile.txt https://api.opentargets.io/v3/platform/public/association/filter --header "Content-Type:application/json"This can be a very powerful way of querying our API: the JSON can be used to pass any combination of the parameters listed in our API documentation.
This was hard!
We realize this is not very user friendly, but we still wanted to show how it is possible to use the API for these kind of queries, particularly for scientists working in computational biology.
Stay tuned, we are working on making this much easier and directly accessible from our web app in our new release!
Originally published at blog.opentargets.org on September 13, 2016.
