In the previous tutorial on REST API over UMLS Terminologies we saw how it would be awesome to have a RESTful API for querying UMLS data and what are some of the common resources to query. We at Applied have one such API, Health Vocab API, and in this tutorial we will introduce the app itself and how to start using it.
This is how we came up with the app:
Chintan mentions:
It was one of those late spring days in NYC, we were coding our patient portal app for the New York eHealth Collaborative Challenge. They provided us with oh-so-SHIN-NY API, but it sent us raw CCDA files and we wanted to display patient friendly lab result names. So we coded up this API that was called by our Javascript client on the patient portal to display nicer lab names.
How is it different from the UMLS Terminology Services?
Our goal with Health Vocabulary REST API was to create a developer friendly API that abstracts-away a lot of UMLS specific notions to support rapid app development. The UTS provides a full-fledged web services based interface. Additionally, this API server can be hosted and managed locally.
Health Vocab API Info:
- Developed in Python/Django
- Open Source
- Core developer: Chintan Patel
- source code at: https://github.com/chintanop/health-vocabulary-rest-api
Current resources provided for consumption(i.e: you can query for):
- Concept Resource
- Terminology Code resource
- Terminology Relationship resource
- Terminology Mapping resource
Many other resources can be identified as per needs, and dataset we have at hand.
Install/Set up
- Check out the code into your local.
- Edit *settings.py( and update DATABASE settings to point to your local database.
- Create corresponding database tables, python manage.py syncdb.
- Load the MRCONSO.sql, MRREL.sql, MRSTY.sql (pronounced as Mr. Conso, Mr. Rel, Mr. Sty) into database from command line as follows:mysql -u<user> -p<password> <db_name> < MRCONSO.sql
alter table MRCONSO add column id int auto_increment primary key;
mysql -u<user> -p<password> <db_name> < MRREL.sql
alter table MRREL add column id int auto_increment primary key;
mysql -u<user> -p<password> <db_name> < MRSTY.sql
alter table MRSTY add column id int auto_increment primary key;
- Run the app, python manage.py runserver
- For production environment, it is advised to host the app inside a WSGI container.
API operations
NOTE: The required field are marked as “bold” in the API parameters
1. GET /concepts
Search concepts by term and source terminology (SAB).
Parameters:
- term: Any source medical term, e.g. diabetes
- sabs: A comma separated list of source vocabularies to restrict the concepts. The full list of vocabulary abbreviations is available here.
- tty: Source term type to restrict the terms, e.g. PT for ‘designated preferred name’, MH for ‘main heading’. The full list of source term types is available here.
- sty – Semantic type to restrict the terms, e.g.T047 for ‘Disease or Syndrome’, T200 for ‘Clinical Drug’. The full list of semantic types is available here.
- partial: 1/0 (if partial=1 then term will be partial term matches will be returned. if partial =0 then all matches will be returned. default =0)
Returns: A list of concept objects
2. GET /concepts_bulk
Search concepts by terms in bulk and source terminology (SAB).
Parameters:
- terms: A comma separate list of terms
- sabs: A comma separated list of source vocabularies to restrict the concepts
- partial: 1/0 (if partial=1 then term will be partial term matches will be returned. if partial =0 then all matches will be returned. default =0) delimiter: delimiter which separates the terms, default is comma(,)
Returns: A list of concept objects
3. GET /concepts/:cui
Get full details for a concept (specified by CUI).
Parameters:
cui: concept id
Returns A Concept object
Example: http://havoc.appliedinformaticsinc.com/concepts/C0027651?demo=true
4. GET /concepts/:cui/children
Get all children for a given concept. By default it will get all children based on UMLS (REL=CHD/RN) or the relationships can be restricted to a given vocabulary.
Parameters:
- cui: concept id
- sab: The source vocabs to restrict the child definition. Currently supported: MeSH and SNOMEDCT
- explode: 1/0 – if set to 1 then get all children recursively. Currently supported vocabularies: MeSH
Returns: A list of Concept objects
Example: http://havoc.appliedinformaticsinc.com/concepts/C0027651/children?sabs=MSH&explode=0&demo=true
5. GET /concepts/:cui/parents
Get all parents for a given concept. By default it will get all parents based on UMLS (REL=PAR/RB) or the relationships can be restricted to a given vocabulary.
Parameters:
- cui: concept id
- sab: The source vocabs to restrict the child definition. explode: 1/0 – if set to 1 then get all parents recursively. Currently supported vocabularies: MeSH
Returns: A list of Concept objects
Example: http://havoc.appliedinformaticsinc.com/concepts/C0027651/parents?sabs=MSH&explode=0&demo=true
6. GET /concepts_bulk/:cui,:cui,:cui/parents
Get all parents for a given list of concepts. By default it will get all parents based on UMLS (REL=PAR,RB) or the relationships can be restricted to a given vocabulary.
Parameters:
- cui list:: list of comma seperated cuis
- sab: The source vocabs to restrict the child definition.
- explode: 1/0 – if set to 1 then get all parents recursively. Currently supported vocabularies: MeSH
Returns: A list of Concept objects for each provided CUI
Example: http://havoc.appliedinformaticsinc.com/concepts_bulk/C0027651,%20C0006826/parents?demo=true
7. GET /concepts/:cui/synonyms
Get all synonym strings for a given Concept (:cui). Optionally, restrict the synonyms to a list of vocabularies.
Parameters:
- cui: concept id
- sabs: A List of source vocabularies
Returns: A list of strings, e.g. [“diabetes”, “diabetes type 2”,…]
Example: http://havoc.appliedinformaticsinc.com/concepts/C0027651/synonyms?demo=true
8. GET /rel/:sab/:code/:rel_type
Get all target codes related to a given vocab/code pair by relationship rel_type.
Parameters:
- sab: The vocabulary abbreviation or short name, e.g. SNOMEDCT, LOINC.
- code: The value of code to be looked up, e.g. 111-ABC degree: Control the number of hops in the graph
- rel_type: The relationship to be looked up, e.g. is_diagnosed_by, causative_agent_of. The full list of relationship attribute types is available here.
Returns: A list of Concept objects
Example: http://havoc.appliedinformaticsinc.com/rel/MSH/D009369/associated_with/?demo=true
**
Code API
** The following set of APIs work with vocabulary codes.
9. GET /codes
Search all codes.
Parameters:
- code: Search for a given code
- sabs: Restrict the search a given set of vocabularies
Returns: A list of Code objects.
Example: http://havoc.appliedinformaticsinc.com/codes?code=D009369&sab=MSH&demo=true
10. GET /codes/:code/sabs/:sab
Get details about a code.
Parameters:
- code: Get details about a code
- sab: In a given source vocabulary
Returns: A Code object.
Example: http://havoc.appliedinformaticsinc.com/codes/D009369/sab/MSH/?demo=true
11. GET /codes/:code1/sabs/:sab1/mapping/:sab2
Get semantically equivalent mappings for code1 in sab1 in sab2
Parameters:
- code1: Get details about a code
- sab1: In a given source vocabulary
- sab2: The target vocabulary to find a code in sab2
Returns: A list of Code objects (one or more mappings).
Example: http://havoc.appliedinformaticsinc.com/map/MSH/D009369/WHO/?demo=true
More resources:
- http://blog.appliedinformaticsinc.com/getting-started-with-metamorphosys-the-umls-installation-tool/
- http://blog.appliedinformaticsinc.com/umls-metathesaurs-tool-mysql-load-scripts-database-browse/
- http://blog.appliedinformaticsinc.com/umls-metathesaurs-loading-umls-schema-data-to-mysql/
- http://blog.appliedinformaticsinc.com/rest-api-over-umls-terminologies/