From Protege Wiki
Revision as of 15:42, November 5, 2008 by JenniferVendetti (talk | contribs) (migrated documentation over from old cim3 wiki)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


by Qi Li, Philip Shilane


Type Tab Widget
Author(s) Qi Li, Philip Shilane
Last Update September 14, 2006
License Mozilla Public License
Homepage UMLS Tab website
For Application

Allows users to search the National Library of Medicine's Unified Medical Language System (UMLS) and annotate Protege ontologies with terms, concept IDs, synonyms, relations, and other information from the UMLS.

Versions & Compatibility

This section lists available versions of UMLS Tab.

VersionCompatible withDependencies
UMLS Tab 2.0Protege-Frames 3.3.1UMLS Metathesaurus License Agreement

If you click on the button below to add a new version of UMLS Tab, you will be asked to define a page title for the new version. Please adhere to the naming convention of UMLS Tab X.X.X when you define the new page!


VersionChanges in this version
UMLS Tab 2.0no change log was maintained for this version


Please note: This documentation contains screenshots of an outdated version of Protege called Protege-2000. The UMLS Tab still works with the latest version of Protege and despite the outdated screenshots, this documentation is still useful.

The UMLS Tab is a customized interface for browsing and searching the UMLS from within Protege, and directly annotating a Protege ontology with information from the UMLS. New instances and classes can be created in Protege or slot values added by directly importing search results from the UMLS.

Introduction to the UMLS

The National Library of Medicine (NLM) sets up the Unified Medical Language System (UMLS). UMLS develops and distributes multi-purpose electronic "Knowledge Sources" and associated lexical programs. The UMLS sources are quite useful for users to set up their knowledge base in the medical domain. All of the concepts, terms, and semantic types in the UMLS come from lots of sources. In the UMLS Tab, users can query directly through the UMLS Knowledge Source server.

To learn more about the UMLS, please visit:

The UMLS Tab is designed to query the UMLS directly through UMLS Knowledge Source Server. The UMLS Tab is a customized interface for:

  • Viewing a remote knowledge base within Protege
  • Directly annotating an ontology in Protege with information from the remote knowledge base
  • Searching UMLS sources by term name
  • Creating new Protege classes and instances with UMLS content
  • New instances and classes can be created in Protege and slot values can be added by directly importing search results from the UMLS Knowledge Source Server
  • The knowledge in the table and relation display can be navigated easily
  • UMLS content can be added selectively to Protege

User Interface Tutorial

Suppose you are using Protege to develop a knowledge base for breast cancer information. The Unifed Medical Language System (UMLS) contains a lot of information that the user would like to include in the knowledge base. You would like to be able to query that information and selectively include it in the knowledge base that you are developing. We will illustrate a sample process below:

View Layout: general layout of the UMLS tab

The tab has four parts:

  • Search text and specification pane is in the upper left of the screen. User can start their search by typing strings in the textfield and choosing suitable search specifications such as approximate or exact match, sources and maximum number of returned results.
  • Presearch results pane is below the search text and specification part. The presearch results are displayed in a table. The results that match the query best are shown first. If a user single-clicks on one of the rows in the table, the detailed information about that entry will be shown in the result part. If a user double-clicks on one row in the table, a new search will be actived with th selected entry as the search term. The undo and redo buttons and the progress bar are located between the search text part and presearch result part. The progress bar shows which fraction of the search process has been completed.The undo and redo buttons display the saved results of earlier or later searches without invoking the search itself. This allows the user to avoid unnecessarily repeating a search and save time.
  • Search results pane is located in the central part of the tab. It consists of several tabbed panes. Each pane is used to display one property of the selected term, for example a definition or a list of synonyms. There are several small icons on each tabbed pane, such as slot, class and instance icons. If you click one of the icons, the selection in the tabbed pane will be added to the knowledge base as slot, class, or instance respectively. There are two icons on the right top of the series of tabbed panes. These icons allow you to add the information in all the panes as a single class or a single instance. Class icon will add search result item as a class with all available slot values from relation display in each tabbed pane. Instance icon will add search result item as an instance with all available slot values.
  • Knowledge-base view is located in the right of screen. The knowledge-base view allows you to view the current state of Protege knowledge base. There are two tabs in this part: classes view and instances view. The Classes View allows you to view the class hierarchy and the Instance View displays the instances in the knowledge base.
    Umls demo1.gif

Searching for the term "Breast Cancer"

  • Type "breast cancer" in the search field and check Approximate Match to look for substring matches. Set maximum number of returned values to 100.
  • Press enter or click on the search button.
  • Closely matched terms are shown in the table, and the detailed information for the first term in the table is shown in the center pane.

Creating Classes and Instances

In the center pane, subclasses of breast cancer are shown in a tree.

To create classes or instances using these terms, select terms from tree. If you want to import these terms as classes, select the desired superclass in the Classes View and click the Class icon. If you want to import these terms as instances, select the direct type in the Instances View and click the Instances button.

Umls demo2.gif

Changing the Search Specifications

If you would like to see only the exact matches as the result of your search, uncheck the Approximate match checkbox. When the search is performed, a progress bar is updated to indicate the current status of the search.

Creating a Class with all of the Available Information

After the search is done, choose Classes View in the right tab.

Click on class icon (with right arrow sign >) on the upper right in the center part. The "breast cancer" class has been created with the all slots which are defined in the first search. The slot values for the selected "breast cancer" class are filled in according to search result.

Umls demo3.gif

Viewing the Newly Created Class

In the Classes View panel on the right, click on the V(iew) button to see the selected "Breast Cancer" class. The detailed information for "Breast Cancer" is shown. All slot values were filled in using search results.

Umls demo4.gif

Troubleshooting Connection Problems

Many people report problems connecting to the UMLSKS servers in the form of remote or connect exceptions. Examples of what these exceptions might look like are: Operation timed out: connect

java.rmi.RemoteException: Connection refused; invalid client IP address

To successfully connect, please verify that you have completed the following items:

  • You are a registered UMLSKS user. If you have not registered, you may request an account on the home page of the UMLSKS Web site.
  • You have added your IP address to your account profile on the UMLSKS Web site. Instruction for doing this are as follows:
    • Go to the UMLSKS Web site.
    • Login to their site using your UMLSKS LoginID and password.
    • Click on the Views/Profiles link on the navigation bar that runs along the top of the page.
    • Add your static IP address to the "IP Address(es)" text area.
    • Click Update Changes to save your changes.
  • If you are running from behind a firewall, confirm that the firewall is configured to allow outside connection to the default RMI service port of 1099.

It is also possible that the UMLSKS system may be down for maintenance or be encountering problems. If the UMLSKS is encountering problems, you can contact them ( and notify them of the problem.

UMLS Releases

The user interface of the UMLS Tab does not allow you to specify which release version of Metathesaurus data to query. As a workaround, we have provided an additional property in the Protege.lax file called "UMLSTab.dbyear" that allows you to specify the desired Metathesaurus release number. The default value is 2004AA. A list of release numbers can be found in the documentation section of the UMLS portion of the National Library of Medicine's Web site.

To modify the UMLSTab.dbyear property in Protege:

  • Select File | Preferences...
  • Click on the Property Files tab in the Preferences dialog.
  • Click on the Protege.lax tab.
  • Locate the entry for the UMLSTab.dbyear property in the Property Table.


  • Double-click in the Value column to edit the value of the UMLS release.


The UMLS Tab and its source code (like Protege) are freely available under the open source Mozilla Public License.

Anyone who wishes to use this plug-in should be aware that the National Library of Medicine requires a signed license agreement in order to use or access UMLS content. The license is free of charge and you are responsible for abiding by the license terms, which protect the rights of the providers of some component vocabularies. You can obtain a copy of the license agreement from the UMLS Information Web site.

Level of Support

This plug-in is no longer under active development. Since the Protege community continues to express interest in the UMLS Tab, the Protege team will answer questions about the tab (as time permits) via the protege-discussion mailing list. We also recompile the UMLS Tab to make sure that it works with each new version of Protege.

The source code for the UMLS Tab is available in the Protege Subversion repository. The URL to browse the code via a Web interface is: The URL to download the source code with a Subversion client is: