fhir2transmart 0.1.2

Example FHIR to TranSMART loader

This package contains a mapper that reads data from HL7 FHIR (STU 3 or R4) resources and translates them to the data model or the TranSMART platform, an open source data sharing and analytics platform for translational biomedical research.

It also provides a utility that applies the mapper and writes the translated data to tab-separated files that can be loaded into a TranSMART database using the transmart-copy tool.

The FHIR reader is based on the fhirclient package, writing to TranSMART is based on transmart-loader.

⚠️ Note: this is a very preliminary version, still under development. Issues can be reported at https://github.com/thehyve/python_fhir2transmart/issues.

Installation

The package requires Python 3.6.

To install fhir2transmart, do:

pip install fhir2transmart

Or from source:

git clone https://github.com/thehyve/python_fhir2transmart.git
cd python_fhir2transmart
pip install .

Run tests (including coverage) with:

python setup.py test

Usage

Read input from a JSON file input.json and write the output in transmart-copy format to /path/to/output. The output directory should be empty of not existing (then it will be created).

# Translate one json file
fhir2transmart input.json /path/to/output
# Translate all json files in a directory
fhir2transmart input_dir /path/to/output

Example data is available at MITRE SyntheticMass. Instructions:

# Download 1K Sample Synthetic Patient Records, FHIR STU3 : 20MB
wget https://syntheticmass.mitre.org/downloads/2017_11_06/synthea_sample_data_fhir_stu3_nov2017.zip
# unzip creates a directory 'fhir' containing 282MB of json files
unzip synthea_sample_data_fhir_stu3_nov2017.zip
# create an output directory
mkdir output
# apply the mapping
fhir2transmart fhir output

This generates the directories i2b2metadata and i2b2demodata in the output directory. The generated data can be loaded using transmart-copy:

# Download transmart-copy:
curl -f -L https://repo.thehyve.nl/service/local/repositories/releases/content/org/transmartproject/transmart-copy/17.1-HYVE-5.9-RC3/transmart-copy-17.1-HYVE-5.9-RC3.jar -o transmart-copy.jar
# Load data
PGUSER=tm_cz PGPASSWORD=tm_cz java -jar transmart-copy.jar -d output

Mapping

The following mapping table shows how FHIR resources are mapped to the TranSMART data model.

FIHR	TranSMART
Resource type	attribute	Class	attribute	concept	modifier
Patient	identifier	PatientMapping	identifier
Patient	gender	Patient	sex
Patient	gender	Observation	value	Gender
Patient	birthDate	Observation	value	BirthDate
Patient	deceased	Observation	value	Deceased
Patient	deceasedDate	Observation	value	DeceasedDate
Condition	subject	Observation	patient
Condition	code	Observation	conceptCode
Condition	onsetDateTime	Observation	startDate
Condition	abatementDateTime	Observation	endDate
Condition	recordedDate	Observation
Condition	category
Encounter	identifier	Visit
Encounter	period.start	Visit	startDate
Encounter	period.end	Visit	endDate
Encounter	status	Visit	activeStatusCd
Encounter	class	Visit	inoutCd
Encounter	hospitalization	Visit	locationCd

License

Copyright (c) 2019, The Hyve

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.