FAQs
General
What does Convert-Pheno do?
Convert-Pheno is an open-source toolkit for converting clinical and phenotypic data between supported exchange models such as BFF, PXF, OMOP-CDM, REDCap, CDISC-ODM, CDISC Dataset-JSON and Dataset-XML, FHIR R4/mCODE, and mapped CSV.
Can Convert-Pheno be used as an ETL tool for CSV-to-OMOP?
Yes. Convert-Pheno can turn mapped CSV records into supported OMOP CSV tables in one command. It uses BFF internally; you do not need to create an intermediate BFF file.
You must provide a mapping file describing the source columns and their meaning. Convert-Pheno writes OMOP CSV tables but does not import them into an OMOP database. Review and validate the tables before importing them. See the CSV guide and BFF to OMOP.
Is Convert-Pheno free?
Yes. See the license.
Is Convert-Pheno or Pheno-Convert?
It's Convert-Pheno, for two reasons:
- The naming is inspired by the
convertutility from ImageMagick. - In related contexts, people refer to PhenoConvert as in PhenoCopy or PhenoConversion.
How mature are the supported conversions?
Convert-Pheno is used in research projects, and its supported routes are covered by automated regression tests. Formats marked experimental are implemented, but have been evaluated with fewer independent datasets or source systems. Validate generated outputs against your project's requirements before operational use.
Were any mappings developed with LLM assistance?
Some newer mappings were drafted or refined with large language model (LLM) assistance when the source standard was especially dense or ambiguous. LLM output is not accepted as mapping evidence on its own: changes require human review, regression testing, and relevant target-format validation.
Specific models and reasoning settings are development tools rather than part of the public conversion contract. The mapping tables document implemented behavior; the code, fixtures, schemas, and validators determine whether that behavior is accepted.
If I use Convert-Pheno to convert my data to Beacon v2 Models, does this mean I have a Beacon v2?
No. Beacon v2 is an API specification, while the Beacon v2 Models are the data models used by that API. Convert-Pheno helps generate compatible data files, but a working Beacon still needs storage and an API layer on top.
What is the difference between Beacon v2 Models and Beacon v2?
Beacon v2 is a specification to build an API. The Beacon v2 Models define the format for the API's responses to queries regarding biological data. With the help of Convert-Pheno, data exchange text files (BFF) that align with this response format can be generated. By doing so, the BFF files can be integrated into a non-SQL database, such as MongoDB, without the API having to perform any additional data transformations internally.
Why are there so many clinical data standards?
Different standards solve different problems: clinical care, research harmonization, case reporting, API exchange, or project-level data capture. Convert-Pheno exists because those formats overlap in practice, but they were not designed as one unified ecosystem.
Are you planning in supporting other clinical data formats?
Afirmative, but it will depend on community adoption. Please check our roadmap for more information.
Are longitudinal data supported?
Although Beacon v2 and Phenopackets v2 allow for storing time information in some properties, there is currently no way to associate medical visits to properties. To address this:
-
omop2bff- we added an ad hoc property (_visit) to store medical visit information for longitudinal events in variables that have it (e.g., measures, observations, etc.). -
redcap2bff- In REDCap, visit/event information is not stored at the record level. We added this information insideinfoproperty.
We raised this issue to the respective communities in the hope of a more permanent solution.
What is an "ontology" in Beacon v2 and Phenopacket v2 context?
In this context, “ontology” is used broadly for standardized identifiers such as HPO, NCIt, LOINC, or RxNorm terms. In practice, these are the coded terms used in the JSON structures handled by Beacon v2 and Phenopackets.
I have a collection of PXF files encoded using HPO and ICD-10 terms, and I need to convert them to BFF format, but encoded in OMIM and SNOMED-CT terminologies. Can you assist me with this?
Not directly. Convert-Pheno converts data models, but it does not rewrite source ontology terms into a different terminology system. If you need ontology remapping, that should be handled as a separate mapping step.
What type of data validation is carried out?
Convert-Pheno uses external validators during development where practical: bff-tools validate from beacon2-cbi-tools for Beacon/BFF output, the extended xt/protobuff.t protobuf parsing test for PXF output, and omop-csv-validator for OMOP CSV output. For BFF mappings, validator failures are used to refine runtime mappings, defaults, and type coercions until generated entity files validate against the Beacon v2 schemas.
Convert-Pheno does not validate the clinical correctness or completeness of your input data. Source files should be checked before conversion.
See Development Validation for details.
What type of database search is carried out?
Convert-Pheno supports indexed exact lookup, strict token ranking with mixed,
and typo-tolerant candidate retrieval with fuzzy. Similarity scores measure
lexical resemblance rather than clinical equivalence. The formulas, worked
NCIT example, threshold behavior, and terminology-audit columns are documented
under Terminology Search.
Why do some Dataset-JSON and Dataset-XML examples contain CDISC: identifiers?
Those identifiers are deliberate source-derived fallbacks, not failed or silently skipped searches. Convert-Pheno does not invent an external ontology crosswalk when the source supplies no authoritative identifier and the data owner has not configured a terminology rule.
The repository keeps baseline and terminology-enriched fixtures separately.
Baseline outputs test structural conversion and preservation of SDTM
field/value identity. Enriched outputs test reviewed mapping-file queries,
direct terms, or exact NCI identifier lookup from Define-XML. Use
--term-audit to distinguish each resolution path in your own conversion.
See Dataset-JSON, Dataset-XML, and Terminology Search.
Error Handling for CSV_XS ERROR: 2023 - EIQ - QUO character not allowed @ rec 1 pos 21 field 1
This usually means the file separator does not match what Convert-Pheno is expecting. See Troubleshooting.
Should I export my REDCap project as raw data or as labels for use with Convert-Pheno?
Prefer raw data together with the REDCap dictionary file. If your export uses labels instead, use the CSV route. See Troubleshooting.
Can I use the mapping file to customize synthesized datasets and cohorts for any *2bff conversion?
No. Mapping-based augmentation of synthesized datasets and cohorts is currently available only for the routes that use a mapping file: csv2bff, redcap2bff, and cdiscodm2bff.
For those conversions, beacon.datasets.defaults and beacon.cohorts.defaults can override metadata such as id, name, description, version, externalUrl, cohortType, or cohortDataTypes.
This does not currently apply to omop2bff or pxf2bff. Dataset-JSON and
Dataset-XML accept a compact mapping file for terminology enrichment only;
it does not override synthesized entity metadata. Those routes prepopulate
dataset and cohort metadata from studyOID and the TS study title.
FHIR also does not read a mapping file. It can prepopulate dataset and cohort
metadata from ResearchStudy and Group resources.
Which formats accept gzipped (.gz) files?
Based on the current I/O code, gzip support is available for these file families:
| File family | Typical use | Read .gz | Write .gz | Notes |
|---|---|---|---|---|
| JSON / YAML structured files | BFF, PXF, JSON-LD, flattened JSON/YAML, mapping files, schema files | Yes | Yes | Implemented through the shared JSON/YAML I/O layer for .json, .yaml, .yml, .jsonld, .yamlld, .ymlld and their .gz variants |
| CSV / TSV / TXT tabular inputs | csv2*, redcap2*, REDCap dictionary files | Yes | N/A | Input readers accept .csv.gz, .tsv.gz and .txt.gz |
| SQL dumps | omop2* from .sql dumps | Yes | N/A | OMOP SQL input accepts .sql.gz |
| Streamed OMOP output | omop2bff --stream | N/A | Yes | CLI restricts streamed OMOP output to json or json.gz |
| OMOP table output | *2omop | N/A | Yes | Use -oomop --out-dir DIR to get TABLE.csv files. Use --out-name TABLE=filename.csv.gz to rename or gzip specific tables |
| CSV / TSV output | bff2csv, pxf2csv, terminology-audit TSV | N/A | Yes | The current writers accept .csv.gz and .tsv.gz in addition to plain text output |
In practice, gzip is supported both for structured JSON/YAML-style outputs and for the main CSV/TSV output paths.
Installation
I am installing Convert-Pheno from source (non-containerized version) but I can't make it work. Any suggestions?
See Troubleshooting.