Skip to main content

Example FHIR to TranSMART loader

Project description

Build status codecov PyPI PyPI - Downloads

This package contains a mapper that reads data from HL7 FHIR (STU 3 or R4) resources and translates them to the data model of 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


The package requires Python 3.6.

To install fhir2transmart, do:

pip install fhir2transmart

Or from source:

git clone
cd python_fhir2transmart
pip install .

Run tests (including coverage) with:

python test


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 [--with-ontology] input.json /path/to/output
# Translate all json files in a directory
fhir2transmart [--with-ontology] input_dir /path/to/output

With the --with-ontology option, concepts and ontology nodes are created based on the input data. Do not use this option when ontologies have already been loaded separately.

Example data is available at MITRE SyntheticMass. Instructions:

# Download 1K Sample Synthetic Patient Records, FHIR STU3 : 20MB
# unzip creates a directory 'fhir' containing 282MB of json files
# 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 -o transmart-copy.jar
# Load data
PGUSER=tm_cz PGPASSWORD=tm_cz java -jar transmart-copy.jar -d output


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

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    


This project was funded by the German Ministry of Education and Research (BMBF) as part of the project DIFUTURE - Data Integration for Future Medicine within the German Medical Informatics Initiative (grant no. 01ZZ1804D).


Copyright (c) 2019 The Hyve B.V.

The FHIR to TranSMART loader is licensed under the MIT License. See the file LICENSE.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fhir2transmart-0.2.1.tar.gz (9.8 kB view hashes)

Uploaded source

Built Distribution

fhir2transmart-0.2.1-py3-none-any.whl (9.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page