malac-hd 0.1.2a1

Mapping Language Compiler for Health Data.

MaLaC-HD

MaLaC-HD (MApping LAnguage Compiler for Health Data) is a tool that you can use to convert mappings between different health data formats to executable code. It can also be used as a library to dynamically execute mappings.

Why?

When having parallel operations of some sort or another, there is one requirement that is challenging in the context of standardized APIs: mapping data, to make it accessible to the different worlds at least.

There are many methods to map from one semi-structured data format to another. Most of the times, when a mapping requirement reveals, it is solved by a quick small script. After some time, that script needs technical or rule updates. As the rules are directly coded, they can only be altered by someone having knowledge about the mapping content, the mapping rules and the mapping technology.

To divide these concerns, HL7 FHIR created resources for mapping purposes, like the StructureMap for transformation and ConceptMap for translation. Additionally a more human readable metalanguage for creating such StructureMap and ConceptMap resources was created, called FHIR Mapping Language, or in short FML. Interestingly enough, FML is not restricted to FHIR as a source or target for the mapping. It could also be used i.e. to map from HL7 CDA to OHDSI OMOP CDM.

Current FML or StructureMap/ConceptMap tools are quite slow in the transformation/translation of the content to be mapped, as both steps, the processing of the rules and the transformation/translation itself is done every time. As a gold standard and sparring partner for this project, the Canadian open source project HAPI with its Suisse extension matchbox has been used. Additionally, we got notice about some Italian project speeding up matchbox, but couldn't find any public references.

We can't use current tools to map data synchronously, as nearly all mapping executions need more time than the dorethy threshold of 0.4 seconds, resulting in the users perception of "it got stuck". Also the practical, but restricted FHIR mapping language does not offer any possibilities to extend it with further functions, in contrast to the StructureMap and ConceptMap resources themselves, that could be easily extended.

How?

Focusing on but not restricting to the health information technology world, a partnership was created out of the experts in the CDA2FHIR HL7 Austria Working Group, to solve this issue. On one side with expertise in research and on the other side with expertise in EHRs.

By applying the MVP concept of build-measure-learn-repeat, first versions were created and tested against already existing FML-mappings in the HL7 community and matchbox as a mapping tool.

As the partners are themselves heavy users of the resulting MVPs, using them immediately after release, quick iterations of four months are planned.

What?

MaLaC-HD is intended to focus on transformation speed and easy extensibility after compilation/convertion. This is achieved by seperation of

• the processing from FML to StructureMap/ConceptMap,
• the conversion from StructureMap/ConceptMap to python code,
• the execution of the translation itself from source to target. It uses the mappings and requirements of some preliminary projects (i.e. https://github.com/HL7Austria/CDA2FHIR) as testing data.

MaLaC-HD is not limited to the use of FML or StructureMap/ConceptMap for the translation, but has already implemented a conversion from StructureMap/ConceptMaps to python code. It can be used to transform/translate different input formats to different output formats, using some conversion/mapping rule language and the XSD or JSON schemas of the input and output format. It also makes it easier to develop new conversion or mapping rule languages, further input formats and/or extensions.

Pursued Objectives

The development of MaLaC-HD focuses on the following three main objectives and their respective sub-objectives:

• The compilation of the conversion/mapping rules by MaLaC-HD and the resulting mapping of these rules in a common programming language must be easily readable and directly related to the conversion/mapping rules.
  • The conversion/mapping rules must be ballotable so that they can be queried and discussed for completeness and correctness as part of a guideline or even as a standalone part in a community, such as the HL7 community.
• MaLaC-HD must not be dependent on any conversion rule language in order to be able to easily process conversion/mapping rules that can be mapped in different conversion rule languages.
  • In particular, the limits of the respective conversion rule language require simple narrative extensibility in order to draw attention to the fact that further code must be added manually in the respective generated code by means of placeholders.
• The result of compiling the conversion/mapping rules must be trimmed for speed and stability so as not to add any obstructive delays.
  • The compiled conversion/mapping rules should be executable as stand-alone program code without MaLaC-HD.

Getting Started

These instructions will get you a copy of the project up and running.

Installation

Install malac-hd and its dependencies via pip:

pip install malac-hd

... or, if you want to build from source:

git clone https://gitlab.com/cdehealth/malac-hd.git
cd malac-hd
pip install -e .

Preparing your FML maps

As the direct support of FML will come with the beta version this fall, a workaround has to be done right now in the alpha, by pre-compiling/converting the FML to StructreMaps and ConceptMaps by using the java-validator, i.e.:

java -jar .\validator_cli.jar -ig ./tests/structuremap/aut_lab/cdaToBundle.map -output tests/structuremap/aut_lab/cda-2-bundle-merged-transform.4.fhir.xml -compile http://hl7.at/fhir/HL7ATCoreProfiles/4.0.1/StructureMap/at-cda-to-bundle -version 4.0

Using MaLaC-HD

with malac-hd --help you will get an overview:

____________________ MaLaC-HD 0.1.1+20240516-alpha started ____________________
usage: malac-hd [-h] -m MAPPING [-co CONVERT_OUTPUT] [-ti TRANSFORM_INPUT] [-to TRANSFORM_OUTPUT] [-s]

This is the MApping LAnguage Compiler for Health Data, short MaLaC-HD. We differentiate between two modes, converting and transforming. The convertion is compiling a given mapping to python code, that itself can be run with its own argument handling for transforming inputs. Additionally, the transformation can   
also be be done by MaLaC-HD directly after convertion, i.e. for direct testing purposes.

options:
  -h, --help            show this help message and exit
  -m MAPPING, --mapping MAPPING
                        the mapping file path, the conversion/mapping rule language is detected by file ending, right now only StructureMaps and ConceptMaps can be given as mappings
  -co CONVERT_OUTPUT, --convert_output CONVERT_OUTPUT
                        the conversion python file path, if not given, saved in the working directory with the map-file name
  -ti TRANSFORM_INPUT, --transform_input TRANSFORM_INPUT
                        the transformation input file path, the ressource type is detected by its root node inside the xml
  -to TRANSFORM_OUTPUT, --transform_output TRANSFORM_OUTPUT
                        the transformation output file path, the ressource type is detected by its root node inside the xml
  -s, --silent          do not print the converted python mapping to console

Example Usage

Usage of an in MaLaC-HD included example:

malac-hd -m ./tests/structuremap/aut_lab/cda-2-bundle-merged-transform.4.fhir.xml -co ./tests/structuremap/aut_lab/out/bundle.4.fhir.xml.py -i ./tests/structuremap/aut_lab/Lab_Allgemeiner_Laborbefund.at.cda.xml -to ./tests/structuremap/aut_lab/out/bundle.4.fhir.xml

Support

Please use our gitlab issues for questions or support.

Authors and acknowledgment

We want to thank

• ELGA GmbH with their CDA2FHIR projects and
• AIT Austrian Institute of Technology GmbH with their SmartFOX project.

Additionally, we want to thank

• Dave Kuhlman with his open source implementation of generateDS, making quick serializations of new data structures from their XSD schemas possible.

License

This is a LGPL licensed project, with a small add on that any usage of this project or results of this project should contain a for the consumer visible icon, that will be announced here in the near future.