MIT-LCP / cwmed

A Python package that facilities the conversion of clinical terminology between two different coding systems for interoperability.

Crosswalk Medical

Introduction

Crosswalk medical faciliates the conversion of clinical terminology between two different coding systems. This enables seemless data exchange, integration and interoperability between different healthcare information systems, overcoming barries imposed by disparate coding systems.

Documentation and Usage

Crosswalk medical is a Python package to assist the semantic interoperability when federating clinical databases. The objective of the package is to guide the crosswalk from one standard source vocabulary to a target vocabulary by defining concepts and utilizing semantic relationships avaliable via downloadable source and target dictionaries on Athena that capture associations between two different concepts.

See Downloading Source and Target Vocabularies section for downloading source and target vocabularies.

See Installation section for package installation.

See demo.ipynb notebook file for example use cases.

Installation

The distribution is hosted on PyPI at: https://pypi.org/project/cwmed/0.1.0/. The package can be directly installed from PyPI using pip:

pip install cwmed

Downloading Source and Target Vocabularies

Register on Athena, log in, and select the desired source and target vocabularies for download.

A link will be sent to your registered email to enable the download of a ZIP file that will include these dependencies:

CONCEPT.csv: This dictionary contains the relation between concept_code and concept_id.
CONCEPT_RELATIONSHIP.csv: This dictionary contains the relationships between the different `concept_id(s). We will use the "Maps to" type of relation to translate codes between dictionaries. These files are dictionaries that need to be stored in the same folder as the python notebook.

Few examaples of downloadable vocabularies avaliable on Athena:

LOINC - Logical Observation Identifiers Names and Codes (Regenstrief Institute)
SNOMED - Systematic Nomenclature of Medicine - Clinical Terms (IHTSDO)
NDC - National Drug Code (FDA and manufacturers)
RxNorm Extension - RxNorm Extension (OHDSI)
RxNorm - RxNorm (NLM)
ICD10CM - International Classification of Diseases, Tenth Revision, Clinical Modification (NCHS)
ICD9CM - International Classification of Diseases, Ninth Revision, Clinical Modification, Volume 1 and 2 (NCHS)
ICD9Proc - International Classification of Diseases, Ninth Revision, Clinical Modification, Volume 3 (NCHS)
CPT4 - Current Procedural Terminology version 4 (AMA)
OMOP Extension - OMOP Extension (OHDSI)

Crosswalk Medical Recipe

Definitions: concept_code: code from the source vocabulary that represents one concept. Example: For the concept (0.5 ML Fondaparinux sodium 5 MG/ML Prefilled Syringe [Arixtra] the concept_code for NDC is: 00007323001 concept_id: code from OMOP that corresponds to a concept_code. Example: For concept (0.5 ML Fondaparinux sodium 5 MG/ML Prefilled Syringe [Arixtra] the concept_id corresponding to concept_code 00007323001 is 44838028.

Every concept_code has a related concept_id. The concept_code does not converge to a concept_id: For the same concept(amoxicillin 250mg Oral Capsule), there will be different OMOP codes(concept_id) one for each vocabulary. Those concept_id(s) are related in the dictionary concept_relationship.

DRUG	VOCAB	concept_code	concept_id
amoxicillin 250 MG Oral Capsule	RX NORM	308182	19073183
amoxicillin 250 MG Oral Capsule	NDC	44420386	43858035231

Every concept_code has a different concept_id even though they represent the same concept in the real world. In the above table, the same drug has two different concept_codes for each vocabulary and also a different concept_id.

Use Case

Use Case: Translate [amoxicillin 250 MG Oral Capsule] from RxNorm code to NDC code.

Step 1: Translate the source code to the OMOP code. CONCEPT_CODE(SOURCE CODE)-- CONCEPT --> CONCEPT_ID(OMOP CODE)

VOCAB	concept_code (RX NORM)	concept_id
RX NORM	308182	19073183

Step 2: Use the concept_relationship dictionary to relate the concept_id obtained from step 1 and map it to the target vocabulary concept_id .

CONCEPT_ID_1(OMOP CODE FROM SOURCE VOCAB) --> CONCEPT_RELATIONSHIP --> CONCEPT_ID_2(OMOP CODE FROM TARGET VOCAB)

source concept_id is concept_id_1 and target concept_id is concept_id_2

concept_id_1	concept_id_2
19073183	44420386

Step 3: Use the new concept_id_2 to obtain the concept_code of the target vocabulary.

CONCEPT_ID_2(OMOP CODE FROM TARGET VOCAB) -->CONCEPT--> CONCEPT_CODE(TARGET CODE)

VOCAB	concept_id	concept_code (NDC)
NDC	44420386	43858035231