Getting Started with MetamorphoSys – The UMLS Installation Tool

by Nadeem Nazeer

What is the UMLS?

The Unified Medical Language System  is a repository of biomedical vocabularies developed by the US National Library of Medicine.

The UMLS integrates over 2 million names for some 900,000 concepts from more than 60 families of biomedical vocabularies, as well as 12 million relations among these concepts.

Vocabularies integrated in the UMLS Metathesaurus include the:

  • NCBI taxonomy
  • Gene Ontology
  • the Medical Subject Headings (MeSH)
  • OMIM
  • the Digital Anatomist Symbolic Knowledge Base.

One powerful use of the UMLS is linking health information, medical terms, drug names, and billing codes across different computer systems. Some examples of this are:

  • Linking terms and codes between your doctor, your pharmacy, and your insurance company
  • Patient care coordination among several departments within a hospital

The UMLS has many other uses, including search engine retrieval, data mining, public health statistics reporting, and terminology research.

In addition to data, the UMLS includes tools for customizing the Metathesaurus (MetamorphoSys), for generating lexical variants of concept names (lvg) and for extracting UMLS concepts from text (MetaMap).

What is MetamorphoSys ?

MetamorphoSys is the UMLS installation wizard and Metathesaurus customization tool included in each UMLS release. It installs one or more of the UMLS Knowledge Sources. 

MetamorphoSys is used for:

  • Creating a custom UMLS Metathesaurus subset and is needed to install the most current UMLS Knowledge Sources.
  • Browsing and querying the Metathesaurus.
  • Getting and exporting the load scripts for use in other applications.

So let’s get started and set up the tool!

Step 1:

First we need access to UTS (UMLS Terminology Services) portal to download the tool & related files.

We need to request a license and sign up for a UMLS Terminology Services (UTS) account. Requesting a UMLS License and creating a UTS account is a two-step process

  • Submit your license request
  • Authenticate the request after receipt of e-mail

More about license requests is available here.

Step 2:

After logging in to the UTS follow the UMLS Knowledge Sources link under the title Downloads in the menu bar.


There are two main releases shown:

  • The full release: The full release includes every vocabulary in the Metathesaurus.
  • The active release: The active release only includes vocabularies that are actively updated in the Metathesaurus.

So we go with downloading full release files. The release files are quite large; downloading is only recommended with a high speed internet connection. 

Currently the files shown for year 2014 are listed below, and those in bold are the data files with big size, and the one in green is the tool itself:

  • 2014AB.CHK
  • 2014AB.MD5
  • 2014AB-1-meta.nlm (1.5 GB)
  • 2014AB-2-meta.nlm (1.4 GB)
  • 2014AB-otherks.nlm (1 GB)
  • (250 MB)
  • Copyright_Notice.txt
  • README.txt
  • 2014AB UMLS Active Release Files

Step 3:

So now we get started in setting environment for setting up the tool itself.

  • The mmsys tool is java based, so be sure to have JRE on your machine; here is a good link, if you don’t have it installed on your machine yet (you can check by typing java –version in your terminal).

To be sure we are on the same page; copy all the downloaded files in the same folder.

  • Now extract the contents in the same folder.
  • Open a terminal window and change to the directory of the downloaded files. Type the appropriate command for your platform:
      • ./run.bat (Windows)
      • ./ (or click on the run_mac.command file)
      • ./
  • You may need to allow the execute permissions for above files to enable them to execute and launch the tool. On unix based systems we just do it by:
      • sudo chmod 777
  • If all goes well , the Metamorphosys tool will be launched (see image below):

umls 1


Step 4:

In order to validate all things are intact just click on File > Validate Distribution,

validation tool

After completion of validation, you will be provided the validation log.  So finally you are all set to install the UMLS resources (Browser, Load Scripts etc).

In the next part we will start installing the tool, getting SQL scripts to work/browse data locally and more.

2 thoughts on “Getting Started with MetamorphoSys – The UMLS Installation Tool”

Leave a Reply

Your email address will not be published. Required fields are marked *

Data Science & PopHealth

Methods, tools, systems for healthcare data analysis

Contact us now

Healthcare Informatics Solutions

Healthcare IT news, developments, opinions and solutions

Contact us now

Popular Posts