A software toolkit for the interconversion of standard data models for phenotypic data

📘 Documentation: https://cnag-biomedical-informatics.github.io/convert-pheno

📓 Google Colab tutorial: https://colab.research.google.com/drive/1T6F3bLwfZyiYKD6fl1CIxs9vG068RHQ6?usp=sharing

📦 CPAN Distribution: https://metacpan.org/pod/Convert::Pheno

🐳 Docker Hub Image: https://hub.docker.com/r/manuelrueda/convert-pheno/tags

Table of contents

• Description
  • Name
  • Synopsis
  • Summary
• README

Convert-Pheno

Convert-Pheno is a toolkit for interconverting standard clinical and phenotypic data models

Supported formats include BFF, PXF, OMOP CDM, REDCap, cBioPortal clinical studies, CDISC-ODM, CDISC Dataset-JSON, FHIR R4, CSV, and openEHR canonical input

Quick Start

Typical CLI usage:

convert-pheno -ipxf pxf.json -obff individuals.json
convert-pheno -ipxf pxf.json -obff --entities individuals biosamples datasets cohorts --out-dir out/
convert-pheno -ibff individuals.json -opxf phenopackets.json
convert-pheno -iomop dump.sql.gz -obff individuals.json.gz --stream --ohdsi-db
convert-pheno -idataset-json dm.json mh.json lb.json -obff individuals.json
convert-pheno -ifhir bundle.json -obff --entities individuals biosamples --out-dir out/
convert-pheno -icbioportal study/ -obff --entities individuals biosamples datasets cohorts --out-dir out/

For backward compatibility, the -iomop ... -obff form still keeps the individuals-only BFF output behavior.

Note: cBioPortal clinical study input, openEHR canonical input, CDISC Dataset-JSON SDTM input, and FHIR R4 Bundle input are currently experimental because independent source coverage remains limited. See the CLI documentation for their implemented routes and current boundaries.

Internally, most conversions use BFF as the target model before continuing to other output formats when needed.

Multi-Entity Output

BFF output can now be entity-aware through --entities.

Current support:

• individuals as the default BFF output entity
• biosamples as first-class BFF output from PXF biosamples, cBioPortal sample tables, FHIR Specimen, OMOP SPECIMEN, or mapping-file rules
• datasets and cohorts synthesized from normalized individuals, with source metadata where supported

Example:

convert-pheno -ipxf pxf.json -obff --entities individuals biosamples datasets cohorts --out-dir out/

This can write:

• out/individuals.json
• out/biosamples.json
• out/datasets.json
• out/cohorts.json

For mapping-file workflows such as csv2bff, redcap2bff, and cdiscodm2bff, synthesized datasets and cohorts can be customized through the top-level beacon section of the mapping file

Mapping Files

Mapping-file based tabular conversions now use an entity-aware layout

• project keeps project-level metadata
• beacon.individuals contains the semantic mapping rules for Beacon individuals
• beacon.datasets, beacon.cohorts, and beacon.biosamples can provide metadata or defaults for emitted Beacon entities

This makes the mapping structure consistent with multi-entity BFF output while keeping individuals as the central normalized model

Selected CLI Features

Useful recent options include:

• --default-vital-status to control the fallback subject.vitalStatus.status in bff2pxf
• --term-audit to write a TSV, compressed TSV, or color-coded XLSX report of terminology resolution
• generic -i/-o syntax in addition to the format-specific shortcuts
• --out-name key=file to customize filenames in multi-file BFF or OMOP output

Installation

Detailed installation instructions live in dedicated Markdown docs:

• Non-containerized installation
• Containerized installation

Repository installs that run cpanm --installdeps . may also need system libraries such as libssl-dev for the SSL/JSONLD dependency chain.

Published documentation:

• https://cnag-biomedical-informatics.github.io/convert-pheno

CLI Documentation

The CLI now keeps concise built-in help in bin/convert-pheno.

Long-form CLI documentation lives in Markdown:

• CLI guide
• Download and installation

Examples

Repository fixtures under t/ double as runnable examples. See the t/ fixture guide for tested inputs, reference outputs, and commands that mirror the regression suite.

Useful examples:

bin/convert-pheno -ipxf t/pxf2bff/in/pxf.json -obff individuals.json
bin/convert-pheno -ipxf t/pxf2bff/in/pxf_biosamples.json -obff --entities individuals biosamples datasets cohorts --out-dir out/
bin/convert-pheno -icsv t/csv2bff/in/csv_data.csv --mapping-file t/csv2bff/in/csv_mapping.yaml --term-audit terminology.tsv -obff individuals.json
bin/convert-pheno -ibff t/bff2pxf/in/individuals.json -opxf phenopackets.json --default-vital-status UNKNOWN_STATUS
bin/convert-pheno -iomop t/omop2bff/in/omop_cdm_eunomia.sql -opxf phenopackets.json
bin/convert-pheno -iomop t/omop2bff/in/gz/omop_cdm_eunomia.sql.gz -obff individuals.json.gz --stream --omop-tables DRUG_EXPOSURE

Citation

If you use Convert-Pheno in published work, please cite:

Rueda, M et al. (2024). Convert-Pheno: A software toolkit for the interconversion of standard data models for phenotypic data. Journal of Biomedical Informatics. https://doi.org/10.1016/j.jbi.2023.104558

Author

Manuel Rueda, PhD. CNAG: https://www.cnag.eu