UMLS tools

version: 0.3.3b1

The umls-tools package is a toolkit to build the UMLS data into a relational database. It also provides an SQLAlchemy object relational mapper and an API for using Metamap. In addition, there are scripts to extract the relationships and build them into a Neo4j graph database.

There is online documentation for umls-tools.

Please note that the code in this package is intended for research use only and not meant for any clinical use.

Installation instructions

At present, umls-tools is undergoing development and no packages exist yet on PyPi. Therefore it is recommended that you install in either of the two ways listed below.

Installation using conda

I maintain a conda package in my personal conda channel. To install from this please run:

conda install -c cfin -c bioconda -c conda-forge umls-tools

There are currently builds for Python v3.8, v3.9 and v3.10 for Linux-64 and Mac-osx. Please keep in mind that all development is carried out on Linux-64 and Python v3.8/v3.9. I do not own a Mac so can't test on one, the conda build does run some import tests but that is it.

Installation using pip

You can install using pip from the root of the cloned repository, first clone and cd into the repository root:

git clone git@gitlab.com:cfinan/umls-tools.git
cd umls-tools

Install the dependencies:

python -m pip install --upgrade -r requirements.txt

Then install using pip

python -m pip install .

Or for an editable (developer) install run the command below from the root of the repository. The difference with this is that you can just to a git pull to update, or switch branches without re-installing:

python -m pip install -e .

Conda dependencies

There are also conda yaml environment files in ./resources/conda/envs that have the same contents as requirements.txt but for conda packages, so all the pre-requisites. I use this to install all the requirements via conda and then install the package as an editable pip install.

However, if you find these useful then please use them. There are Conda environments for Python v3.8, v3.9 and v3.10.

Next steps...

You might want to setup a database connection config file if you are using any RDMS other than SQLite.

You will also want to install a copy of the UMLS database.

Although the umls_tools.parse module is deprecated, it does require the GeniaTagger to be installed. The path to the binary should be set in an environment variable called GENIATAGGER in your ~/.bashrc. If you do not plan to use the umls_tools.parse module then this is optional.

If you plan to use Metamap, you will also need to install it locally, you will need to login to the NLM for that.

There is also an experimental Neo4j build script you can try but read below first.

In addition to the Python command-line scripts that are available when the package is installed. There are also some bash administrative scripts located in ./resources/bin. Please note these will not be installed when you install via clone & pip or a conda install. If using conda you will have to clone the repo. With either install method you will need to add the ./resources/bin directory to your PATH.

These scripts will require two bash libraries to be in your PATH.

1. shflags - This <https://github.com/kward/shflags>_ is to manage bash command line arguments.
2. bash-helpers - This <https://gitlab.com/cfinan/bash-helpers>_ wraps some handle bash functions.

For more information on what is available see the bash script documentation.

Change log

version 0.3.0a0

• API - Add a generalisable index module (umls_tools.admin.index) for creating index tables in the UMLS and other databases. This also offers some basic index search options.
• API - Added an umls_tools.orm_mixin module, to generalise index table creation.
• API - Updated the ORM to add index tables to the UMLS schema.
• API - Deprecated the umls_tools.parsers module.
• SCRIPTS - Added a UMLS database index script to create index tables from the MRCONSO.STR fields.

version 0.3.1a0

• API - Updated to use SQLALchemy 2 - This will cause some warnings when the ORM module is loaded. I am currently investigating this.