DISNET API DOCUMENTATION

Version Information
Version Date Author Description
1.0.0 13-12-2017 Gerardo Lagunes García
(gerardo.lagunes@ctb.upm.es)
Initial draft
1.1.0 09-05-2018 Gerardo Lagunes García
(gerardo.lagunes@ctb.upm.es)
Update the services: diseaseWithMoreDisnetConcepts and diseaseWithFewerDisnetConcepts
1.1.1 17-05-2018 Gerardo Lagunes García
(gerardo.lagunes@ctb.upm.es)
Add includeCode parameter
1.2.0 23-09-2020 David Fernández Lobón
Lucía Prieto Santamaría
Add new API endpoints for querying DISNET's biological layer
1.3.0 26-04-2021 Marina Díaz Uzquiano Change token authorization to optional
1.4.0 30-01-2021 Marina Díaz Uzquiano Add new API endpoints for querying the pharmacology layer
Getting Started
Base URL

disnet.ctb.upm.es/api/disnet

Schemes

HTTP | HTTPS

Requirements

The use of a token is not required to query this API. However, if a user wants to keep a history of their requests, they can build them using the token given upon signing up.

Quick Start

Overview of API usage.

  1. Select tool. To visualize the results of the requests there are two ways to do it: 1) with a Web viewer, use the one of your preference (Opera, Chrome, Firefox, Safari, IE, among others) and 2) some program that allows to consume Web services, we recommend the use of Postman available for users Windows, Mac OS X, Linux and Chrome in its official Web page https://www.getpostman.com.
  2. Select service of your interest from DISNET's list of official services.
  3. Make a query by setting the requested search parameters according to each service.
  4. Send the formed query.
  5. Visualize the query response.

REST API Introduction

Currently the DISNET API has thirty-one endpoints, eleven of them query DISNET's phenotypical layer, and the remaining twenty query the biological layer. In the Service List section we can see the detailed list of services offered by DISNET with a short description of its function.

In our system, we call "DISNET Concept" to all terms (symptoms) that have been validated, since the ones that have not passed the validation process are not considered "signs or symptoms". All the queries that return a list of DISNET Concepts, return by default the validated ones. But it is possible to parametrize the queries to return non-validated terms.

These queries attempt to provide as much relevant data as possible to the end users. They can consult from the sources that have been mined, the snapshots, the list of all diseases from a given source and snapshot, to the configuration of a particular snapshot.

You can also look at some predefined queries here in a Postman collection file.

NLP Tools and Configuration

Metamap1 was developed by the National Library of Medicine (NLM) and is one of the most widely accepted applications of NLP in biomedicine. When Metamap analyzes texts and identifies words or phrases, it relates and assigns them to concepts of NLM's Unified Medical Language System (UMLS), so we have terms that can be used by other biomedical applications that use the unique identifier concept (CUI) of UMLS (Aronson, 2001; Park et al., 2015).

In our research work regarding DISNET's phenotipical layer, we processed the texts of our database with Metamap version 2016v2.

To add Metamap to the DISNET system we have developed a Web service that consumes Metamap by means of a request that contains the indications of its configuration. Next, we will describe the part of the request that is related to the Metamap configuration.

The standard configuration we use with Metamap first includes a list of semantic types of concepts to be detected from a much larger list provided by this tool2. Our own configuration is shown in Fig. 1. The semantic types we use are 6: Acquired Abnormality (acab), Anatomical Abnormality (anab), Cell or Molecular Dysfunction (comd), Congenital Abnormality (cgab), Disease or Syndrome (dsyn), Experimental Model of Disease (emod), Finding (fndg), Mental or Behavioral Dysfunction (mobd), Neoplastic Process (neop), Pathologic Function (patf), Sign or Symptom (sosy), Laboratory or Test Result (lbtr), Clinical Attribute (clna), Mental Process (menp), Diagnostic Procedure (diap) and Laboratory Procedure (lbpr). If we only focus on detecting sosy concepts, the scope of discovering phenotypic manifestations for a disease would be very limited. Extending the filter over the texts, telling Metamap to look for other types of concepts allows you to retrieve more diagnostic concepts.

Let's look at an example of the filtering Metamap does with our configuration, taking a piece of text obtained from the Signs and symptoms section of the Wikipedia article about the Brain Salt-wasting Syndrome3 extracted on February 1st, 2018: “Advanced symptoms[sosy] include muscle cramps[sosy], lightheadedness[sosy], dizziness[sosy] or vertigo[sosy], feelings of anxiety or panic[fndg] (not mentally induced), increased heart rate or slowed heart rate, low blood pressure[fndg] and orthostatic hypotension[fndg] sometimes resulting in fainting[sosy]”. The words or phrases that Metamap has detected, along with their semantic types, are indicated in bold letters. We clearly observe that there are four words that were detected with the semantic type fndg, which are phenotypical manifestations of the syndrome and if we had not indicated that semantic type we would lose consciousness.

The next configuration element is source, which lists the subset of source vocabularies in which we want Metamap to search, first of all we use SNOMEDCT_US and DSM-54.

Another essential configuration element is, options, which determine which options to activate for filtering, for example, when we indicate "-y" we are telling Metamap to activate word disambiguation. And when we write "-R" we saying Metamap to use the vocabulary list that we have previously indicated. To see all Metamap options you can visit the following link5.


Fig. 1. Standard options and settings for Metamap

Finally, we find the concept_location option that allows us to indicate Metamap to return extra information about the location of each concept found. This information includes the word or words by which the NLP tool found some concept and its position within the text. In this link, in the "Performing" section to query using the API we find information about everything we can get from Metamap through its Java development API.

We do not rule out using any other NLP tool, in the analysis of the related work we mention some of them that can help us to obtain better results.

Service List

Phenotype layer
Query path Short description
1 /pheno/sources Retrieve source list
2 /pheno/snapshots Retrieve all snapshots for a given source
3 /pheno/disnet-diseases Retrieve the list of diseases defined by a disnet id
4 /pheno/disnet-diseases?name={name} Search disnet diseases by name
5 /pheno/disnet-diseases/{disnet-id}/url Retrieve the urls associated to a disease belonging to a certain source and snapshot
6 /pheno/disnet-diseases/{disnet-id}/symptoms Retrieve diseases with more DISNET Concepts for a given source and snapshot
7 /pheno/symptoms Retrieve all symptoms in the phenotypic layer
8 /pheno/symptoms?name={name} Search symptoms by name
9 /pheno/symptoms/{cui}/disnet-diseases Get the list of disnet diseases presenting a certain symptom in their clinical picture
10 /pheno/metadata Retrieve metadata for a given source and snapshot
Biology layer
Query path Short description
12 /bio/diseases Retrieve all diseases from the biology layer
13 /bio/diseases?name={name} Retrieve the disease id of a given disease name
14 /bio/diseases/{disease-id}/genes Retrieve genes associated to a given disease
15 /bio/diseases/{disease-id}/variants Retrieve variants associated to a given disease
16 /bio/genes Retrieve all genes in the biology layer
17 /bio/genes/{gene-id} Retrieve information about a given gene
18 /bio/genes/{gene-id}/diseases Retrieve diseases associated to a given gene
19 /bio/genes/{gene-id}/proteins Retrieve proteins associated to a gene
20 /bio/genes/{gene-id}/pathways Retrieve pathways associated to a given gene
21 /bio/genes/{gene-id}/variants Retrieve variants associated to a given gene
22 /bio/variants Retrieve all variants in DISNET's biological layer
23 /bio/variants/{variant-id} Retrieve information of a given variant
24 /bio/variants/{variant-id}/diseases Retrieve diseases associated to a given variant
25 /bio/variants/{variant-id}/genes Retrieve genes associated to a given variant
26 /bio/pathways Retrieve all pathways in the biology layer
27 /bio/pathways/{pathway-id} Retrieve pathway information
28 /bio/pathways/{pathway-id}/genes Retrieve genes involved in the given pathway
29 /bio/proteins Retrieve all proteins in the biology layer
30 /bio/proteins/{protein-id}/genes Retrieve genes associated to a given protein
31 /bio/ppis Retrieve all PPIs in the biology layer
Pharmacology layer
Query path Short description
32 /pharma/diseases Retrieve all diseases in the pharmacology layer
33 /pharma/diseases?name={name} Search by name and retrieve information about a disease in the pharmacology layer
34 /pharma/diseases?id={id} Search by id and retrieve information about a disease in the pharmacology layer
35 /pharma/diseases/{disease-id}/drugs Retrieve all drugs associated to a disease in the pharmacology layer
36 /pharma/phenotypes Retrieve all phenotype effects
37 /pharma/phenotypes?name={name} Search by name and retrieve information about a phenotype effect
38 /pharma/phenotypes?id={id} Search by id and retrieve information about a phenotype effect
39 /pharma/phenotypes/{phenotype-id}/drugs Retrieve all drugs associated to a phenotype effect
40 /pharma/drugs Retrieve all drugs
41 /pharma/drugs?name={name} Search by name and retrieve information about a drug
42 /pharma/drugs?id={id} Search by name and retrieve information about a drug
43 /pharma/drugs/{drug-id}/diseases Retrieve all diseases in the pharmacology layer associated to a drug
44 /pharma/drugs/{drug-id}/phenotypes Retrieve all phenotype effects associated to a drug
45 /pharma/drugs/{drug-id}/targets Retrieve all targets to a specific drug
46 /pharma/drugs/{drug-id}/interactions Find drugs that interact with the query drug
47 /pharma/drugs/{drug1-id}/interactions/
{drug2-id}/phenotypes
Find phenotype effects produced by drug-drug interactions
48 /pharma/targets Retrieve all targets
49 /pharma/targets?name={name} Search by name and retrieve information about a target
50 /pharma/targets?id={id} Search by id and retrieve information about a target
51 /pharma/targets/{target-id}/drugs Retrieve all drugs associated to a target