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) Updating the services: diseaseWithMoreDisnetConcepts and diseaseWithFewerDisnetConcepts
1.1.1 17-05-2018 Gerardo Lagunes García (gerardo.lagunes@ctb.upm.es) Add includeCode parameter
Getting Started
Base URL

disnet.ctb.upm.es/api/disnet

Schemes

HTTP | HTTPS

Requirements

The requirement to use this API is to have a DISNET account. When an account is generated, an access token (unique identifier) is provided. The token must always be included in every request made to a service, if it is active the service will respond to the request made, otherwise the results will not be displayed.

The token is obtained by signing up in the DISNET Web application, which can be found here.

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 eleven queries, in 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 those terms we store that are validated positively (symptoms) as the medical concepts that were validated negatively and that therefore are not symptoms or signs. All our queries that respond with a list of DISNET Concepts by default return the validated ones positively, but also allow to return the validated ones negatively.

These queries are made with a view to providing as much relevant data as possible to users, so they can be consulted from the sources of knowledge that have been mined, the snapshots that have been made, the list of all diseases from a source and a snapshot, to the configurations by which a particular snapshot has been created.

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 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

Query path Short description
1 /query/sourceList Retrieve sources list
2 /query/versionList Retrieve all available snapshots for a given source
3 /query/diseaseList Retrieve diseases list for a given source and snapshot
4 /query/disnetConceptList Retrieve DISNET Concept list for a given source and snapshot. Search by disease: exact name or not, other vocabulary code, excluding or forcing semantic types.
5 /query/diseaseCount Retrieve number of diseases for a given source and snapshot
6 /query/diseaseWithMoreDisnetConcepts Retrieve disease(s) with more DISNET Concepts for a given source and snapshot
7 /query/diseaseWithFewerDisnetConcepts Retrieve disease(s) with fewer DISNET Concepts for a given source and snapshot
8 /query/mostCommonDisnetConcepts Retrieve most common DISNET Concepts for a given source and snapshot
9 /query/lessCommonDisnetConcepts Retrieve less common DISNET Concepts for a given source and snapshot
10 /query/searchByDiseaseName Retrieve disease(s) for a given source and snapshot by exact name or not
11 /query/metadata Retrieve metadata for a given source and snapshot