TOOLS: MetaMap

Documentation: Installation

MetaMap Installation:

If you are installing MetaMap on Windows XP or Windows 7 use the MetaMap Windows Installation Instructions instead.

Move the downloaded file into a directory where you want to install MetaMap. This directory will then be referred to as <parent_directory> throughout the rest of the installation instructions.

To extract the MetaMap distribution, use the following bunzip2 and tar commands substituting the appropriate name of the file you downloaded (e.g., public_mm_linux_2010.tar.bz2, public_mm_macosx_2010.tar.bz2):

	% bunzip2 -c public_mm_<platform>_<year>.tar.bz2 | tar xvf - 
      
This set of commands will create the distribution directory public_mm in the current working directory (<parent_directory>). So you will have created <parent_directory>/public_mm.

To begin the initial install, go to the directory created when you extracted the distribution (public_mm).

% cd public_mm
      

You can speed up the process by telling the install program where your java installation is by setting the environment variable JAVA_HOME to the Java installation directory. If you don't set the variable the program will prompt you for the information.

To find out where your java installation is located, use the following command:

% which java
	

To set the environment variable JAVA_HOME, use the information from the which command. For example, if the command: which java returns /usr/local/jre1.8/bin/java, then JAVA_HOME should be set to /usr/local/jre1.8/.

in C Shell (csh or tcsh):

setenv JAVA_HOME /usr/local/jre1.8

in Bourne Again Shell (bash):

export JAVA_HOME=/usr/local/jre1.8

Bourne Shell (sh):

JAVA_HOME=/usr/local/jre1.8
export JAVA_HOME
	

You also need to add the <parent dir>/public_mm/bin directory to your program path:

in C Shell (csh or tcsh):

setenv PATH <parent dir>/public_mm/bin:$PATH

in Bourne Again Shell (bash):

export PATH=<parent dir>/public_mm/bin:$PATH

Bourne Shell (sh):

PATH=<parent dir>/public_mm/bin:$PATH
export PATH
      

Now you are ready to run the installation script:

% ./bin/install.sh

A successful installation should look similar to the following:

% cd <parent dir>/public_mm
% ./bin/install.sh
Enter basedir of installation [<parent dir>/public_mm] <user hits return to get the default>
Basedir is set to <parent dir>/public_mm.

The WSD Server requires Java Runtime Environment (JRE)
Java Developer Kit (JDK) will work as well. if the
command: "which" java returns /usr/local/jre1.8/bin/java, then the
JRE resides in /usr/local/jre1.8/.

Where does your distribution of JRE reside?
Enter home path of JRE (JDK) [/usr]: /nfsvol/nls/tools/Linux-i686/java1.8
Using /nfsvol/nls/tools/Linux-i686/java1.8 for JAVA_HOME.

<parent dir>/public_mm/WSD_Server/config/disambServer.cfg generated
<parent dir>/public_mm/WSD_Server/config/log4j.properties generated
<parent dir>/public_mm/bin/SKRrun generated.
<parent dir>/public_mm/bin/metamap generated.
<parent dir>/public_mm/bin/wsdserverctl generated.
<parent dir>/public_mm/bin/skrmedpostctl generated.
Install complete.

%
	

MetaMap requires the starting of one or two servers depending on how you plan to use MetaMap. The SKR/MedPost Part-of-Speech Tagger Server is required regardless of how you use MetaMap. The Word Sense Disambiguation (WSD) Server is optional and only needs to be started if you want/plan to use the WSD option (-y) with MetaMap. They can be started and stopped as follows. Both servers will automatically run in the background when started.

Starting the SKR/Medpost Part-of-Speech Tagger Server:
% ./bin/skrmedpostctl start
Starting the Word Sense Disambiguation (WSD) Server (optional):
% ./bin/wsdserverctl start

You can stop the each server by invoking the corresponding script with the stop parameter:

Stopping the SKR/Medpost Part-of-Speech Tagger Server:
% ./bin/skrmedpostctl stop
Stopping the Word Sense Disambiguation (WSD) Server:
% ./bin/wsdserverctl stop
You can determine if the server are running by the command:
% ps -ef | grep java
The output should look something like this:
11318 pts/4    S+     0:00 grep java
21254 ?        Sl     0:10 /usr/local/j2sdk1.8.0_24/bin/java -cp  ... /MedPost-SKR/Tagger_server/lib/mps.jar taggerServer
21267 ? Sl 0:10 /usr/local/j2sdk1.8.0_24/bin/java -Xmx2g ...
WSD_Server/lib/log4j-1.2.8.jar wsd.server.DisambiguatorServer
      
Once the servers have been started and verified, you can test your MetaMap installation by using the following command:
% echo "lung cancer" | ./bin/metamap -I
You should see a result similar to the following:
metamap (2019)

Control options:
  composite_phrases=4
  lexicon_year=2018
  mm_data_year=2018AB
  lexicon=db
  show_cuis
Processing USER.tx.1: lung cancer

Phrase: lung cancer
Meta Mapping (1000):
  1000   C0242379:Lung Cancer (Malignant neoplasm of lung) [Neoplastic Process]
Meta Mapping (1000):
  1000   C0684249:LUNG CANCER (Carcinoma of lung) [Neoplastic Process]
Meta Mapping (1000):
  1000   C1306460:Lung cancer (Primary malignant neoplasm of lung) [Neoplastic Process]
	
If there are no errors starting the WSD and Tagger servers, and you had a successful test, then MetaMap can be run as follows:
% ./bin/metamap

MetaMap has a plethora of options that are explained elsewhere (MetaMap 2009 Usage, MetaMap 2008 Usage, or MetaMap 2007 Usage).

Binary Update Installation:

After downloading the binary update archive file, first move to the directory containing the directory of the existing public_mm installation and then extract the archive using tar.

$ cd <directory containing existing public_mm installation>
$ tar xvfj public_mm_{os}_binary_{year}.tar.bz2
      

Notes for users migrating from MetaMap09 to MetaMap10

If you are upgrading from MetaMap 2009 to MetaMap 2010, make the following modification to your public_mm/DB directory:

$ cd public_mm/DB
$ ln -s BDB4/\* .
      
This will make any databases configured for MetaMap 09 visible to MetaMap 10.

Removing the MetaMap Installation:

Before un-installing MetaMap, make sure both of the MetaMap servers have been stopped (see Stopping the servers).

To un-install MetaMap move to the parent directory of your Metamap installation and run the uninstall program:

% cd <parent directory of installation>
% ./public_mm/bin/uninstall.sh
Do you really want to uninstall MetaMap? [no/yes] yes
Removing Tagger Server
Removing WSD Server
Removing Lexicon
Removing MetaMap Databases
Removing Programs
Removing Base Directory
Removal of MetaMap installation successful.
%
      

1. Installing the Linux MetaMap 2020 in WSL

A guide for installing the Linux version of MetaMap in the Windows Subsystem for Linux (WSL).

1.1. Setting up WSL on Windows 10

From an administrator enabled instance of PowerShell, run the following commands:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Then restart your system for the changes to take effect.

1.2. Installing WSL Ubuntu App

Use the Microsoft store to download and launch the "Ubuntu 20.04 LTS" app.

At the prompts in the Ubuntu window, enter a username and password for the WSL Ubuntu instance.

You can stop the instance at anytime by typing exit at the "user@DESKTOP-xxxx: $" prompt. You can start a new Ubuntu Linux instance using the "Ubuntu" icon in the start menu.

1.3. Installing Java in the Ubuntu Instance

The Java runtime environment (JRE) is necessary to run the tagger server used by MetaMap. Install the JRE in the Ubuntu Window using the command:

$ sudo apt-get install default-jre

The command will prompt you for the password you provided when you first launched the Ubuntu instance. The JRE will be installed after providing the password.

1.4. Downloading MetaMap

Download the main MetaMap distribution from the MetaMap downloads page (http://metamap.nlm.nih.gov/MainDownload.shtml) to your Downloads folder.

From the Ubuntu window move to the area you wish to work in and extract MetaMap from the Downloads directory. WSL maps the C: drive to "/mnt/c" in the Ubuntu window.

$ cd /mnt/c/Users/username/workdir
$ tar xvfj /mnt/c/Users/username/Downloads/public_mm_linux_main_2020.tar.bz2

See the MetaMap Installation Guide (https://metamap.nlm.nih.gov/Installation.shtml) for the rest of the installation instructions.

Note: when starting the tagger serverbin/ (using the command: bin/skrmedpostctl start) windows will prompt you for network access. You must allow access to run MetaMap which requires the tagger server to run.

Also, these instructions should also work with other WSL Linux apps, but only the Debian and Ubuntu apps have been tested.

See also:

Author: Willie Rogers

Created: 2021-12-07 Tue 11:30