Choose a Conversion

Choose your input format first. Each recipe shows the required source options and one complete command. The output can then be changed with the shared output forms below.

For accepted files and format-specific behavior, see Supported Formats. For every implemented route, tested inputs and reference outputs are available in the repository's t/ fixture guide.

Find Your Input

Input	Main outputs	Required setup
Beacon v2 / BFF	PXF, OMOP-CDM	Beacon individuals JSON or YAML
cBioPortal	BFF, PXF, OMOP-CDM	Unpacked study directory or ZIP archive
CDISC-ODM	BFF, PXF, OMOP-CDM	Mapping file; REDCap dictionary only for REDCap-origin ODM
CSV	BFF, PXF, OMOP-CDM	Mapping file
CDISC Dataset-JSON	BFF, PXF, OMOP-CDM	SDTM domain files including DM
CDISC Dataset-XML	BFF, PXF, OMOP-CDM	SDTM domain files and Define-XML
FHIR R4 / mCODE	BFF, PXF, OMOP-CDM	One or more JSON Bundles
OMOP-CDM	BFF, PXF	CSV tables or SQL dump
OpenClinica ODM	BFF, PXF, OMOP-CDM	Mapping file; metadata embedded in Snapshot ODM
openEHR	BFF, PXF	Canonical JSON or YAML compositions
Phenopackets v2 / PXF	BFF, OMOP-CDM	Phenopacket JSON or YAML
REDCap	BFF, PXF, OMOP-CDM	Data export, dictionary, and mapping file

Select the Output

The recipes use BFF output unless BFF is the input. Replace the final output line with the form you need:

Output	Command ending
BFF individuals	-obff individuals.json
Multiple BFF entities	-obff --entities individuals biosamples datasets cohorts --out-dir bff_out/
Phenopackets v2	-opxf phenopackets.json
OMOP-CDM tables	-oomop --out-dir omop_out/ --ohdsi-db

OMOP output requires the Athena-OHDSI database. Multi-entity BFF output writes the requested entities for which the source provides or supports data. See the Command-Line Interface for naming and --out-dir behavior.

Before using project data, install the tool through Download & Installation and run a small fixture for the selected route. The Command-Line Interface documents all options.

Model Inputs

Phenopackets v2 / PXF

convert-pheno \
  -ipxf phenopacket.json \
  -obff individuals.json

Use the multi-entity BFF ending when the Phenopacket contains biosamples that should be written as Beacon biosamples. Details: Phenopackets v2 and PXF to BFF mapping.

Beacon v2 / BFF

convert-pheno \
  -ibff individuals.json \
  -opxf phenopackets.json

For OMOP-CDM, use the OMOP output ending above. Details: Beacon v2 Models, BFF to PXF mapping, and BFF to OMOP mapping.

OMOP-CDM

convert-pheno \
  -iomop PERSON.csv CONCEPT.csv CONDITION_OCCURRENCE.csv \
  -obff individuals.json

Include SPECIMEN.csv and select biosamples for specimen-derived BFF output. For large SQL dumps, add --stream; add --ohdsi-db when concept lookup needs the Athena-OHDSI database. Details: OMOP-CDM and OMOP to BFF mapping.

Mapping-File Inputs

These routes use a project mapping to turn source fields into BFF terms. The same mapped records can be written directly as BFF, PXF, or OMOP-CDM.

CSV

convert-pheno \
  -icsv clinical.csv \
  --mapping-file mapping.yaml \
  --term-audit terminology.tsv \
  -obff individuals.json

Use --sep when the delimiter differs from the configured default. Details: CSV, Mapping Files, and Terminology Search.

REDCap

convert-pheno \
  -iredcap redcap.csv \
  --redcap-dictionary redcap-dictionary.csv \
  --mapping-file mapping.yaml \
  --term-audit terminology.tsv \
  -obff individuals.json

Details: REDCap and Mapping Files.

CDISC-ODM

convert-pheno \
  -icdisc-odm study.xml \
  --mapping-file odm-mapping.yaml \
  -obff individuals.json

For REDCap-origin ODM, reuse the REDCap mapping profile and add --redcap-dictionary dictionary.csv. Details: CDISC-ODM.

OpenClinica ODM

convert-pheno \
  -icdisc-odm openclinica-export.xml \
  --mapping-file openclinica-mapping.yaml \
  -obff individuals.json

OpenClinica Snapshot ODM uses the CDISC-ODM route, but resolves field metadata from the XML rather than a REDCap dictionary. Details: OpenClinica ODM.

Structured Clinical Inputs

cBioPortal

convert-pheno \
  -icbioportal study/ \
  -obff --entities individuals biosamples datasets cohorts \
  --out-dir bff_out/

Clinical files are discovered through their meta descriptors. A mapping file is optional. Details: cBioPortal and cBioPortal to BFF mapping.

CDISC Dataset-JSON

convert-pheno \
  -idataset-json dm.json mh.json ae.json lb.json \
  -obff individuals.json

Supply one SDTM domain per file; DM is required. All supplied domains are currently loaded and grouped by USUBJID in memory. Add --mapping-file sdtm-terminology.yaml and --term-audit terminology.tsv when the data owner has reviewed terminology rules. Details: CDISC Dataset-JSON and Dataset-JSON to BFF mapping.

CDISC Dataset-XML

convert-pheno \
  -idataset-xml dm.xml mh.xml ae.xml lb.xml \
  --define-xml define.xml \
  -obff individuals.json

Define-XML resolves domain and column metadata before rows are grouped by participant in memory. Supported NCI identifiers in Define-XML are resolved automatically; an optional source.profile: sdtm mapping can handle additional reviewed terms. Details: CDISC Dataset-XML and Dataset-XML to BFF mapping.

FHIR R4 and mCODE

convert-pheno \
  -ifhir bundle.json \
  -obff individuals.json

Generic R4 and mCODE 4.0 use the same command; profile URLs are detected automatically. Select multi-entity output for Specimen-derived biosamples. Details: FHIR R4 and FHIR to BFF mapping.

openEHR

convert-pheno \
  -iopenehr patient-set.json \
  -obff individuals.json

Multiple canonical JSON or YAML compositions can be supplied and are grouped by resolved patient identity. Details: openEHR and openEHR to BFF mapping.

Useful Additions

Need	Option
Stable output for fixture comparison	--test
Terminology decision review	--term-audit terminology.tsv
Smaller BFF without copied source columns	--no-source-info
Separate Beacon entity files	--entities ... --out-dir bff_out/
Incremental OMOP SQL processing	--stream with -iomop ... -obff

Inspection Outputs

BFF and PXF input can also be flattened for inspection and downstream tools:

convert-pheno -ibff individuals.json -ocsv individuals.csv
convert-pheno -ibff individuals.json -ojsonf individuals.flattened.json
convert-pheno -ibff individuals.json -ojsonld individuals.jsonld

These outputs do not replace schema-aware BFF, PXF, or OMOP-CDM output.

Search Mode for Mapping Files

The default exact search is appropriate when source labels match ontology database labels. Use mixed when they differ:

convert-pheno \
  -icsv clinical.csv \
  --mapping-file mapping.yaml \
  --search mixed \
  --min-text-similarity-score 0.8 \
  --term-audit terminology.tsv \
  -obff individuals.json

See Terminology Search for resolution precedence, scoring, and audit-column interpretation.