A software toolkit for the interconversion of standard data models for phenotypic data
[](https://github.com/cnag-biomedical-informatics/convert-pheno/actions/workflows/build-and-test.yml) [](https://coveralls.io/github/CNAG-Biomedical-Informatics/convert-pheno?branch=main) [](https://github.com/cnag-biomedical-informatics/convert-pheno/actions/workflows/cpan-publish.yml) [](https://cpants.cpanauthors.org/dist/Convert-Pheno)  [](https://github.com/cnag-biomedical-informatics/convert-pheno/actions/workflows/docker-build-multi-arch.yml) [](https://hub.docker.com/r/manuelrueda/convert-pheno/) [](https://hub.docker.com/r/manuelrueda/convert-pheno/) [](https://github.com/cnag-biomedical-informatics/convert-pheno/actions/workflows/documentation.yml) [](https://opensource.org/licenses/Artistic-2.0) [](https://colab.research.google.com/drive/1T6F3bLwfZyiYKD6fl1CIxs9vG068RHQ6?usp=sharing) --- **📘 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](#description) - [Name](#name) - [Synopsis](#synopsis) - [Summary](#summary) - [README](README.source.md) # 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: ```bash 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: ```bash 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](non-containerized/README.md) - [Containerized installation](docker/README.md) Repository installs that run `cpanm --installdeps .` may also need system libraries such as `libssl-dev` for the SSL/JSONLD dependency chain. Published documentation: -