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 the name Convert-Pheno or Pheno-Convert?

The name is Convert-Pheno. It was chosen for two reasons:

1. The naming is inspired by the convert utility from ImageMagick.
2. 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 other clinical data formats planned?

Yes, when there is a concrete use case and representative test data. See Future Plans for the formats currently under consideration.

Are longitudinal data supported?

Yes, with model-specific limits. OMOP-to-BFF writes one individual per person and aggregates longitudinal events into that record. When visit context is available, mapped events carry the private _visit extension. REDCap event context is retained in source provenance.

Beacon v2 has no Visit or Encounter entity, so a person record and a person-at-timepoint snapshot must not be treated as equivalent. Mapping Steps explains the two representations in detail.

What is an "ontology" in Beacon v2 and Phenopacket v2 context?

Here, “ontology” is shorthand for the standardized coded terms used by Beacon v2 and Phenopackets, including HPO, NCIt, LOINC, and RxNorm identifiers.

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?

exact performs indexed label or identifier lookup. mixed adds order-independent token matching, and fuzzy can retrieve candidates with one missing or misspelled token. Similarity measures text, not clinical equivalence. See Terminology Search for scoring, thresholds, and audit fields.

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?

Yes, for supported entity-aware BFF routes. Mapping V2 has two relevant forms:

• CSV, REDCap, and CDISC-ODM use full mappings because their source fields are project-specific. cBioPortal can optionally augment its built-in clinical mapping.
• OMOP, PXF, FHIR, openEHR, i2b2, PCORnet, and Sentinel use a compact optional metadata mapping. Their structural conversion remains built in.

In both forms, project.id, beacon.datasets.defaults, and beacon.cohorts.defaults can identify and describe synthesized entities. Dataset-JSON and Dataset-XML instead prepopulate this metadata from studyOID and the TS study title; their optional mapping is for terminology enrichment.

FHIR metadata from ResearchStudy and Group is retained as the source-derived baseline and can be overridden by the compact mapping. Project metadata is not currently copied into individual or biosample records.

Which formats accept gzipped (.gz) files?

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

Structured JSON/YAML and the main CSV/TSV output paths can therefore be written directly as gzip files.

Installation

I am installing Convert-Pheno from source (non-containerized version) but I can't make it work. Any suggestions?

See Troubleshooting.