QuickUMLS Documentation

QuickUMLS supports a client-server architecture to allow multiple scripts to query a single running server.

1. Start the Server: Run the server module via CLI. You can specify host, port, and QuickUMLS options. python -m quickumls.server /path/to/quickumls/files {-P QuickUMLS port} {-H QuickUMLS host} {QuickUMLS options}

• Default host/port: localhost:4645.
• To run in background: Use nohup and redirect output to a .pid file.

2. Use the Client: Import get_quickumls_client from quickumls. The client API is identical to the standard QuickUMLS object.

from quickumls import get_quickumls_client

# Connect to the running server
matcher = get_quickumls_client()

text = "The ulna has dislocated posteriorly from the trochlea of the humerus."
results = matcher.match(text, best_match=True, ignore_syntax=False)

QuickUMLS requires a valid UMLS installation on disk.

1. Obtain UMLS: Obtain a license from the NLM, download UMLS files, and install them using MetamorphoSys. You will specifically need MRCONSO.RRF and MRSTY.RRF.
2. Install the package: Use pip or setup.py.
   • pip install quickumls
   • python setup.py install
   • Note for macOS: Using Anaconda is strongly recommended. If installation fails, install leveldb first via conda install -c conda-forge python-leveldb.
3. Initialize QuickUMLS: Run the installation module to create the QuickUMLS data files from your UMLS installation.

python -m quickumls.install <umls_installation_path> <destination_path>

QuickUMLS can be added as a SpacyQuickUMLS component to a spaCy pipeline. It adds entity objects to the Doc object. These entities store the CUI, similarity score, and Semantic Types in the spaCy ._ (underscore) attribute.

from quickumls.spacy_component import SpacyQuickUMLS
import spacy

# common English pipeline
nlp = spacy.load('en_core_web_sm')

quickumls_component = SpacyQuickUMLS(nlp, 'PATH_TO_QUICKUMLS_DATA')
nlp.add_pipe(quickumls_component)

doc = nlp('Pt c/o shortness of breath, chest pain, nausea, vomiting, diarrrhea')

for ent in doc.ents:
    print('Entity text : {}'.format(ent.text))
    print('Label (UMLS CUI) : {}'.format(ent.label_))
    print('Similarity : {}'.format(ent._.similarity))
    print('Semtypes : {}'.format(ent._.semtypes))

Use python -m quickumls.install to initialize the system. This process takes 5-30 minutes.

Arguments:

• <umls_installation_path>: Path to UMLS files (must contain MRCONSO.RRF and MRSTY.RRF).
• <destination_path>: Directory where QuickUMLS data files will be created.
• -L / --lowercase: Fold concept terms to lowercase (increases recall, may reduce precision).
• -U / --normalize-unicode: Convert non-ASCII characters to closest ASCII equivalents.
• -E / --language: Specify language (default is English).
• -d / --database-backend: Specify backend. Options are leveldb or unqlite. unqlite is the default for v1.4+ and supports multi-process reading and better unicode support.

python -m quickumls.install <umls_installation_path> <destination_path>

Use the get_quickumls_client factory function to create a client instance for interacting with a QuickUMLS server. By default, it attempts to connect to localhost on port 4645. You can specify a custom host and port if your server is running elsewhere.

from quickumls import get_quickumls_client

# Connect to a server on the default localhost:4645
client = get_quickumls_client()

# Connect to a server on a specific host and port
client = get_quickumls_client(host='192.168.1.100', port=5000)

The run_quickumls_server(opts) function initializes a QuickUMLS matcher instance using the provided options and then starts the network server using run_server. This is the primary entry point for launching the server logic.

from quickumls.server import run_quickumls_server
from argparse import Namespace

# Mocking the opts object expected by the function
opts = Namespace(
    quickumls_fp='/path/to/data',
    threshold=0.7,
    overlapping_criteria='score',
    similarity_name='jaccard',
    window=5,
    min_match_length=3,
    verbose=False,
    keep_uppercase=False,
    host='localhost',
    port=4645
)

run_quickumls_server(opts)

You can start a QuickUMLS server from the command line to provide UMLS concept matching services over a network. The server requires the path to your QuickUMLS data files and accepts various configuration options for similarity thresholds, matching criteria, and server networking.

# Example command to run the server
python -m quickumls.server /path/to/quickumls_data --host 0.0.0.0 --port 4645 --threshold 0.8