Choose a Conversion

Start with the input format. The table lists its main outputs, required files, and a link to a working command. Format guides contain the less common options and input constraints.

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
i2b2	BFF, PXF, OMOP-CDM	Exported star-schema tables, directory, or ZIP
OMOP-CDM	BFF, PXF	CSV/TSV files, directory, ZIP, or SQL dump
OpenClinica ODM	BFF, PXF, OMOP-CDM	Mapping file; metadata embedded in Snapshot ODM
openEHR	BFF, PXF	Canonical JSON or YAML compositions
PCORnet CDM	BFF, PXF, OMOP-CDM	Exported tables, directory, or ZIP
Phenopackets v2 / PXF	BFF, OMOP-CDM	Phenopacket JSON or YAML
REDCap	BFF, PXF, OMOP-CDM	Data export, dictionary, and mapping file
Sentinel CDM	BFF, PXF, OMOP-CDM	Exported tables, directory, or ZIP

Select the Output

The examples use BFF output unless BFF is the input. Replace the final output line when another target is needed:

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 supported by the source.

Before using project data

Complete installation, run one small example, and review the guide for your input format. The CLI reference documents shared options and output naming.

Model Inputs

Phenopackets v2 / PXF

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

Use entity-aware BFF output when Phenopacket biosamples should be written as Beacon biosamples. See Phenopackets v2.

Beacon v2 / BFF

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

For OMOP-CDM, use the OMOP output ending above. See Beacon v2 Models.

OMOP-CDM

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

The same tables can be supplied as one directory or ZIP package. Add the clinical tables needed by the conversion; include SPECIMEN.csv for biosamples. See OMOP-CDM.

Mapping-File Inputs

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

CSV

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

See CSV and Mapping Files.

REDCap

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

See REDCap and Mapping Files.

CDISC-ODM

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

REDCap-origin ODM also uses its REDCap dictionary. See CDISC-ODM.

OpenClinica ODM

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

OpenClinica Snapshot ODM resolves metadata from the XML. See OpenClinica ODM.

Structured Clinical Inputs

cBioPortal

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

See cBioPortal.

CDISC Dataset-JSON

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

Exactly one DM domain is required. See Dataset-JSON.

CDISC Dataset-XML

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

Dataset-XML requires Define-XML and exactly one DM domain. See Dataset-XML.

FHIR R4 and mCODE

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

mCODE uses the same command and is detected from profile URLs. See FHIR R4 and mCODE.

openEHR

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

See openEHR.

i2b2

convert-pheno \
  -ii2b2 i2b2-export/ \
  -obff individuals.json

See i2b2.

PCORnet CDM

convert-pheno \
  -ipcornet pcornet-tables.zip \
  -obff individuals.json

See PCORnet CDM.

Sentinel CDM

convert-pheno \
  -isentinel sentinel-export/ \
  -obff individuals.json

See Sentinel CDM.

Useful Options

Need	Option
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 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

For terminology search modes and audit interpretation, see Terminology Search.

Find Your Input​

Select the Output​

Model Inputs​

Phenopackets v2 / PXF​

Beacon v2 / BFF​

OMOP-CDM​

Mapping-File Inputs​

CSV​

REDCap​

CDISC-ODM​

OpenClinica ODM​

Structured Clinical Inputs​

cBioPortal​

CDISC Dataset-JSON​

CDISC Dataset-XML​

FHIR R4 and mCODE​

openEHR​

i2b2​

PCORnet CDM​

Sentinel CDM​

Useful Options​

Inspection Outputs​