Skip to content

UMLS

The Unified Medical Language System (UMLS) brings together many health and biomedical vocabularies and standards to enable interoperability between systems. UMLS Quick Start Guide provides an overview of the software, tools and services associated with the UMLS.

BioServices.UMLS is a Julia module that interfaces with the UMLS REST API to query the UMLS data programmatically.

Getting Started

  1. Sing up for a UMLS Terminology Services (UTS) account, where you agree to their terms of use.

  2. Import module:

    using BioServices.UMLS

Available Endpoints

For a complete list of the enpoints made available in the REST API visit the REST API Documentation

This module focuses in the following three enpoints. (Request to expand API is encouraged trhough pull requests or issues in out GitHub repository.)

EndPoint Description
/cas/v1/tickets Authentication
/search/version Retrieves CUI when searching by term or code
/content/version/CUI Retrieves information about a known CUI
  • CUI refers to Concept Unique Identifier

Exported Functions

The following functions access the mentioned enpoints. See the method's documentation for specific usage

Function Description
get_tgt Get a ticket-granting ticket
search_umls Search UMLS Rest API
best_match_cui Return concept ID of best match for a serach
get-cui Get information associated with a Concept ID(CUI)
get_semantic_types Retrieve smenatic types associated with a CUI

Sample workflow

Service tickets are needed each time you search or retrieve content from the UMLS REST API. A service ticket is retrieved automatically by this software from a ticket granting ticket.

Therefore, the first step of your workflow must start by requesting a ticket granting ticket from your credentials. Two methods are available

Use username and password

    user = "myuser"
    psswd = "mypsswd"
    tgt = get_tgt(username=user, password=psswd)

Use API KEY

    apikey = "myapikey"
    tgt = get_tgt(apikey=apikey)

According to the UMLS documentation. Ticket granting tickets are valid for 8 hours, therefore we locally store the ticket in a file and reuse it if it has not expired. If you get errors, you can force getting a new ticket. For instance

   tgt = get_tgt(force_new=true, apikey=apikey)

After authentication, you can query the CUI associated with a term (e.g obesity) and the semantic types associated with that term (e.g obesity is a Disease or Syndrome)

    term = "obesity"
    query = Dict("string"=>term, "searchType"=>"exact" )
    all_results= search_umls(tgt, query)
    cui = best_match_cui(all_results)   #cui="C0028754"
    sm = get_semantic_types(tgt, cui)   #sm[1] == "Disease or Syndrome"

Options for searchType

  • Word: breaks a search term into its component parts, or words, and retrieves all concepts containing any of those words. For example: If you enter "Heart Disease, Acute" a Word search will retrieve all concepts containing any of the three words (heart, or disease, or acute). Word is the default Search Type selection and is appropriate for both English and non-English search terms.
  • Approximate Match: applies lexical variant generation (LVG) rules to the search term and generally results in expanded retrieval of concepts. For example, a search for the term "cold" retrieves all concepts that contain any of the following words: COLDs, chronic obstructive lung disease, chronic obstructive lung diseases, cold, colder, coldest.
  • Exact Match: retrieves only concepts that include a synonym that exactly matches the search term.
  • Normalized String: use with English language terms only. Removes lexical variations such as plural and upper case text and compares search terms to the Metathesaurus normalized string index to retrieve relevant concepts.
  • Normalized Word: use with English language terms only. Removes lexical variations such as plural and upper case text, and compares search terms to the Metathesaurus normalized word index to retrieve relevant concepts.
  • Right Truncation: retrieves concepts with synonyms that begin with the letters of the search term. For example, a right truncation search for "bronch" retrieves concepts that contain synonyms such as bronchitis, bronchiole, bronchial artery.
  • Left Truncation: retrieves concepts with synonyms that end with the letters of the search term. For example, a left truncation search for "itis" retrieves concepts that contain synonyms such as colitis, bronchitis, pancreatitis.

Method's documentation

Get ticket-granting ticket

# BioServices.UMLS.get_tgt — Method.

get_tgt(; force_new::Bool = false, kwargs...)

Retrieve a ticket granting ticket (TGT) using

  1. UTS username and password OR
  2. apikey

A tgt is valid for 8 hours. Therefore, look for UTS_TGT.txt in the local directory to see if it has been recently stored. One can force getting a new ticket by passing keyword argument force_new=true

Examples

tgt = get_tgt(username = "myuser", password = "mypass")

tgt = get_tgt(apikey = "mykey")

source

Search UMLS

# BioServices.UMLS.search_umls — Method.

search_umls(tgt, query)

Search UMLS Rest API. For more info see UMLS_API

Arguments

  • tgt: Ticket Granting Ticket
  • query: UMLS query containing the search term
  • version: Optional - defaults to current

Output

  • result_pages: Array, where each entry is a dictionary containing a page of

results. e.g

Dict{AbstractString,Any} with 3 entries:
"pageSize"   => 25
"pageNumber" => 1
"result"     => Dict{AbstractString,Any}("classType"=>"searchResults","result…

Examples

credentials = Credentials(user, psswd)
tgt = get_tgt(credentials)
term = "obesity"
query = Dict("string"=>term, "searchType"=>"exact" )
all_results= search_umls(tgt, query)

source

Best CUI

# BioServices.UMLS.best_match_cui — Method.

best_match_cui(result_pages)

Retrieve the best match from array of all result pages

Example

cui = best_match_cui(all_results)

source

Search based on CUI

# BioServices.UMLS.get_cui — Method.

get_cui(tgt,cui)

Retrieve information (name, semantic types, number of atoms, etc) for a known CUI from latest UMLS version or a specific release.

Returns UTS json response

See: https://documentation.uts.nlm.nih.gov/rest/concept

Example

tgt = get_tgt(apikey = "mykey")
cui = "C0028754"
concept = get_cui(tgt, cui)

source

Semantic types

# BioServices.UMLS.get_semantic_types — Method.

get_semantic_types(c::Credentials, cui)

Return an array of the semantic types associated with a cui

Example

tgt = get_tgt(apikey = "mykey")
cui = "C0028754"
sm = get_semantic_types(tgt, cui)

source