Enhancing semantic interoperability in precision medicine: converting OMOP CDM to Beacon v2 in the Spanish IMPaCT-Data project
This is the companion repository for our BMC Medical Informatics and Decision Making article. It provides a tutorial for the paper's file-based workflow: converting OMOP CDM 5.4 SQL exports or CSV tables into JSON for the individuals entity of the GA4GH Beacon v2 Models.
The paper also describes an on-the-fly architecture that connects a PostgreSQL OMOP CDM database directly to a Beacon v2 API. That architecture is outside the scope of this tutorial.
The notebook uses synthetic EUNOMIA data and covers:
- installation of the tested Convert-Pheno 0.34 release;
- SQL-dump conversion and export of parsed OMOP tables as CSV;
- standard and memory-efficient streaming conversion;
- selection of specific OMOP CDM tables; and
- calculation of conversion-completeness statistics.
Run the interactive version in Google Colab:
The version tracked in this repository is nb/omop_cdm_2_beacon_v2_tutorial.ipynb.
The notebook is designed for a Linux-based Google Colab runtime: it uses /content, apt-get, and google.colab. To use it in a local Jupyter environment, adapt those Colab-specific paths and cells. Generated files are written to /content and are removed when the Colab runtime is recycled.
Caution
The tutorial data are synthetic. Do not upload confidential, personal, or patient-identifiable data to a managed Colab runtime unless that use has been approved by your institution and complies with the applicable governance and data-protection requirements. Use an appropriately controlled environment for sensitive data.
Convert-Pheno performs the file-based transformation demonstrated in the notebook:
If you use this tutorial in your work, please cite:
Rueda M, Ramírez-Anguita JM, López-Sánchez V, et al. Enhancing semantic interoperability in precision medicine: converting OMOP CDM to Beacon v2 in the Spanish IMPaCT-Data project. BMC Medical Informatics and Decision Making. 2026.