Conversion Routes

This page is the quickest way to choose a conversion route. Start with your input format, then pick the output you need and copy the matching command.

Most users

Use the command-line interface for real files, mapping files, REDCap dictionaries, OMOP tables, audit TSV files, and multi-entity BFF output.

For a compact list of accepted inputs and outputs, see Supported Formats. Route-specific setup details remain on the linked format pages.

Choose by Input Format

Phenopackets v2 / PXF Input

Target output	Route	Notes
Beacon v2 / BFF	pxf2bff	Supports individuals; can also emit biosamples, datasets, and cohorts with --entities
OMOP-CDM CSV	pxf2omop	Writes OMOP tables to --out-dir
Inspection output	Additional outputs	Flattened JSON, CSV, JSON-LD, YAML-LD

Beacon v2 / BFF Input

Target output	Route	Notes
Phenopackets v2 / PXF	bff2pxf	Input is Beacon individuals JSON/YAML
OMOP-CDM CSV	bff2omop	Writes OMOP tables to --out-dir
Inspection output	Additional outputs	Flattened JSON, CSV, JSON-LD, YAML-LD

OMOP-CDM Input

Target output	Route	Notes
Beacon v2 / BFF	omop2bff	Use --ohdsi-db when concept lookup against Athena-OHDSI is needed
Phenopackets v2 / PXF	omop2pxf	Internally goes through BFF

REDCap Input

Target output	Route	Notes
Beacon v2 / BFF	redcap2bff	Requires --mapping-file and usually --redcap-dictionary
Phenopackets v2 / PXF	redcap2pxf	Uses the same mapping model as redcap2bff

CSV Input

Target output	Route	Notes
Beacon v2 / BFF	csv2bff	Requires --mapping-file
Phenopackets v2 / PXF	csv2pxf	Requires --mapping-file

CDISC-ODM Input

Target output	Route	Notes
Beacon v2 / BFF	cdisc2bff	Requires --mapping-file
Phenopackets v2 / PXF	cdisc2pxf	Requires --mapping-file

Before You Run

• Install the tool first: Download & Installation.
• Use --test when comparing example outputs because it removes time-changing metadata.
• Use --search-audit-tsv FILE for mapping-file conversions if you want to inspect ontology lookup results.
• Use --no-source-info only when you want smaller BFF output and do not need copied source columns under info.
• Use --entities only with -obff and --out-dir when writing multiple Beacon entity files.

Command Examples

PXF Input: BFF Output

Individuals-only BFF output:

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

Entity-aware BFF output:

convert-pheno -ipxf phenopacket.json -obff \
  --entities individuals biosamples datasets cohorts \
  --out-dir bff_out/

Use this when your Phenopacket contains biosample data and you want first-class Beacon biosamples output instead of keeping biosample content under individuals.info.

More detail: Phenopackets v2, PXF to BFF mapping.

PXF Input: OMOP-CDM Output

convert-pheno -ipxf phenopacket.json -oomop --out-dir omop_out/

More detail: OMOP-CDM.

BFF Input Examples

BFF Input: PXF Output

convert-pheno -ibff individuals.json -opxf phenopacket.json

Set the fallback Phenopackets vital status when no source value is available:

convert-pheno -ibff individuals.json -opxf phenopacket.json \
  --default-vital-status UNKNOWN_STATUS

More detail: Beacon v2 Models, BFF to PXF mapping.

BFF Input: OMOP-CDM Output

convert-pheno -ibff individuals.json -oomop --out-dir omop_out/

More detail: BFF to OMOP mapping.

OMOP-CDM Input Examples

OMOP-CDM Input: BFF Output

Individuals-only BFF output from OMOP CSV tables:

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

Biosamples output from OMOP SPECIMEN:

convert-pheno -iomop PERSON.csv CONCEPT.csv SPECIMEN.csv \
  -obff --entities biosamples --out-dir bff_out/

Large OMOP SQL dump with OHDSI lookup:

convert-pheno -iomop dump.sql.gz -obff individuals.json.gz \
  --stream --ohdsi-db

Smaller BFF output without copied OMOP source columns:

convert-pheno -iomop dump.sql.gz -obff individuals.json.gz \
  --stream --ohdsi-db --no-source-info

More detail: OMOP-CDM, OMOP to BFF mapping, Output Validation.

OMOP-CDM Input: PXF Output

convert-pheno -iomop dump.sql.gz -opxf phenopackets.json \
  --stream --ohdsi-db

This route internally maps OMOP data to BFF before writing Phenopackets.

Mapping-File Input Examples

Mapping-file routes are for project-specific tabular data where source columns need to be mapped to Beacon terms. This includes CSV, REDCap, and CDISC-ODM.

CSV Input: BFF Output

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

Multi-entity BFF output with mapping-file metadata for datasets and cohorts:

convert-pheno -icsv clinical.csv \
  --mapping-file mapping.yaml \
  --search-audit-tsv search-audit.tsv \
  -obff --entities individuals datasets cohorts \
  --out-dir bff_out/

More detail: CSV, mapping file, DB search.

CSV Input: PXF Output

convert-pheno -icsv clinical.csv \
  --mapping-file mapping.yaml \
  -opxf phenopackets.json

REDCap Input: BFF Output

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

More detail: REDCap, Tutorial.

REDCap Input: PXF Output

convert-pheno -iredcap redcap.csv \
  --redcap-dictionary redcap-dictionary.csv \
  --mapping-file mapping.yaml \
  -opxf phenopackets.json

CDISC-ODM Input: BFF Output

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

More detail: CDISC-ODM.

CDISC-ODM Input: PXF Output

convert-pheno -icdisc study.xml \
  --mapping-file mapping.yaml \
  -opxf phenopackets.json

Inspection Outputs

For BFF or PXF input, Convert-Pheno can also write inspection-oriented outputs:

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 are useful for review and downstream tooling, but they are not replacements for schema-aware BFF, PXF, or OMOP-CDM output.

Search Mode for Mapping Files

Use exact unless your mapping file contains labels that differ from ontology database labels.

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

For interpretation of audit and validation output, see Output Validation.