Skip to main content

Command-Line Interface

Convert-Pheno includes a command-line utility for file-based conversions. This is the primary way most users work with the project.

The CLI is organized around one input format, one output format, and optional controls for BFF entities, mapping files, ontology search, streaming, and source provenance.

Choose a conversionMapping filesCheck installation
-ipxf -obffPhenopackets to BFFWrite individuals or selected Beacon entities.-iomop -obffOMOP to BFFConvert PERSON, CONCEPT, SPECIMEN, and other OMOP tables.--mapping-fileMapped tabular dataUse CSV, REDCap, or CDISC-ODM with terminology auditing.-ibff -opxfBFF to PhenopacketsGenerate Phenopackets from Beacon individuals input.--entitiesMulti-entity BFFWrite individuals, biosamples, datasets, and cohorts to an output directory.--helpOption groupsReview mapping, OMOP, search, streaming, and output controls.

Command Model​

Every command has three parts:

PartMeaningExample
InputWhat format is being read-ipxf phenopacket.json
OutputWhat format is being written-obff individuals.json
OptionsExtra behavior--entities individuals biosamples --out-dir out/

The most important distinction is BFF output mode:

  • -obff FILE writes one individuals file.
  • -obff --entities ... --out-dir DIR writes one file per requested BFF entity.
Detailed CLI reference

Basic pattern​

The command is organized around one input format and one output format:

convert-pheno -i <input-type> <infile> -o <output-type> <outfile> [options]

Both CLI styles are supported:

  • Generic form: -i pxf ... -o bff ...
  • Compact form: -ipxf ... -obff ...

The compact flags are still the ones most users rely on:

  • -ipxf, -ibff, -icbioportal, -iomop, -iopenehr, -iredcap, -icdisc-odm, -idataset-json, -idataset-xml, -ifhir, -icsv
  • -obff, -opxf, -oomop, -ocsv, -ojsonf, -ojsonld
Experimental source profiles

cBioPortal clinical packages, openEHR canonical input, CDISC Dataset-JSON and Dataset-XML SDTM input, and FHIR R4 Bundle input are implemented but marked experimental while independent source coverage grows. Standard/OpenClinica CDISC-ODM and the bounded ODM 2.0 ClinicalData profile are also experimental beyond the established REDCap ODM workflow. Dataset-JSON, Dataset-XML, and FHIR can write BFF, PXF, or OMOP-CDM; openEHR currently writes BFF or PXF.

You can always check the current built-in help with:

convert-pheno --help

BFF output modes​

BFF output has two explicit CLI forms:

  • individuals-only BFF output: -obff FILE
  • Entity-aware output: -obff --entities ... --out-dir DIR

In other words, --entities does not replace -obff. It refines which BFF entities are written after you have already selected BFF as the output format.

Notes​

  • -obff keeps the individuals-only BFF behavior.
  • BFF entity mode is also explicit: use -obff --entities ... --out-dir DIR.
  • When PXF input contains biosamples, the individuals-only -obff FILE path still writes only individuals. In that mode, convert-pheno warns and preserves the biosamples under info.phenopacket.biosamples.
  • --entities can be used with BFF output. The supported output entities are individuals, biosamples, datasets, and cohorts.
  • biosamples are emitted from PXF biosample data, cBioPortal sample clinical tables, FHIR Specimen, OMOP SPECIMEN, or explicit beacon.biosamples.rules in mapping-file routes.
  • datasets and cohorts are synthesized from the normalized individuals collection.
  • In mapping-file conversions, beacon.biosamples defines first-class biosample rules, while beacon.datasets.defaults and beacon.cohorts.defaults override synthesized metadata.
  • These mapping features are available for csv2bff, redcap2bff, and cdiscodm2bff; cBioPortal accepts the same Mapping V2 structure optionally to augment its built-in patient and sample mapping.
  • --entities narrows BFF output. It must be combined with -obff and --out-dir.
  • --out-name key=file lets you override one multi-file output name. Use entity keys for BFF entity mode and table keys for OMOP output.
  • --no-source-info omits raw source provenance copied into BFF info, such as OMOP_columns, CSV_columns, REDCap_columns, CDISC_ODM, cbioportal, datasetJson.domains, datasetXml.domains, and fhir resources. Mapped fields and info.convertPheno are kept.
  • --term-audit FILE writes a TSV, compressed TSV, or color-coded XLSX audit of direct terms, identifier lookups, label searches, and fallbacks, including retrieval paths, decision reasons, candidate scores, score margins, and provenance.
  • --stream is mainly relevant for large OMOP inputs. Use --no-stream to force the default in-memory mode when a wrapper or previous option may have enabled streaming.

Important options​

Mapping-file conversions​

  • --mapping-file FILE supplies a Mapping V2 YAML or JSON document targeting Beacon schema 2.0.0. It is required by CSV, REDCap, and CDISC-ODM routes; optional for cBioPortal augmentation and Dataset-JSON/Dataset-XML terminology enrichment.
  • --redcap-dictionary FILE or -rcd FILE supplies the dictionary required by REDCap CSV and REDCap-origin ODM. Standard/OpenClinica ODM uses embedded metadata and rejects this option.
  • --schema-file FILE lets you validate mapping files against an alternative JSON Schema.
  • --self-validate-schema or -svs performs a self-validation of the mapping schema itself. This is mainly an author or development check and may require SSL support in the Perl environment.
  • --term-audit FILE writes a terminology-decision report selected by the .tsv, .tsv.gz, or .xlsx extension. The audit includes source values and labels, lookup inputs, converted terms, retrieval paths, decision reasons, candidate scores and margins, provenance, fallbacks, and effective search settings.

CDISC-ODM-specific behavior​

  • -icdisc-odm FILE or -i cdisc-odm FILE accepts Snapshot XML using ODM 1.3.1, 1.3.2, or the bounded ODM 2.0 ClinicalData profile.
  • Version and vendor profile are detected from the ODM namespace, ODMVersion, source system, and extension namespaces. Version-specific input flags are not used.
  • REDCap-origin ODM uses source.profile: redcap with --redcap-dictionary. Standard or OpenClinica ODM uses source.profile: cdisc-odm and embedded MetaDataVersion, ItemDef, and CodeList metadata.
  • Repeated item groups are kept as separate occurrences for repeated BFF sections; ambiguous repeated scalar values stop the conversion instead of overwriting data.
  • The route is available through the CLI and local module interfaces, but not through the HTTP(s) API.

cBioPortal-specific behavior​

  • -icbioportal PATH or -i cbioportal PATH accepts an unpacked cBioPortal study directory or .zip archive.
  • Clinical data files are discovered through meta_*.txt descriptors. The sample table is required; a missing patient table is derived from sample-to-patient links.
  • Entity-aware BFF output can emit patient-derived individuals, sample-derived biosamples, a study-derived dataset, and case-list-derived cohorts.
  • A mapping file using source.profile: cbioportal is optional and may augment project-specific patient and sample fields. It cannot rewrite PATIENT_ID or SAMPLE_ID.
  • Timeline and molecular files are currently outside this clinical package profile. Directory and ZIP input is available through the CLI and local module interfaces, not the HTTP(s) API.

Ontology search tuning​

  • --search exact|mixed|fuzzy selects the ontology lookup strategy. Default: exact.
  • --text-similarity-method cosine|dice selects the token-similarity method used by mixed and fuzzy. Default: cosine.
  • --min-text-similarity-score FLOAT sets the minimum score accepted by mixed and fuzzy. Default: 0.8.
  • --levenshtein-weight FLOAT sets the normalized Levenshtein weight used by fuzzy. Default: 0.1.

For resolution precedence, audit columns, and threshold tradeoffs, see Terminology Search.

OMOP-specific options​

  • --ohdsi-db enables Athena-OHDSI lookup. It is required for OMOP output and optional for OMOP input when concepts are absent from the supplied CONCEPT table.
  • --path-to-ohdsi-db DIR points to the directory containing ohdsi.db.
  • --omop-tables TABLE ... restricts which OMOP-CDM tables are processed, while CONCEPT and PERSON stay included.
  • --exposures-file FILE provides a CSV list of OMOP concept_id values to be treated as exposures.
  • --stream enables incremental OMOP processing for -iomop ... -obff output. Use --no-stream to explicitly keep the default non-streaming mode.
  • --sql2csv prints SQL tables instead of converting them.
  • --max-lines-sql N caps rows read per SQL table and individuals emitted by non-streaming OMOP conversions, including CSV/TSV input. CSV/TSV streaming is not capped by this option. Default: 500.

openEHR-specific options​

  • -iopenehr FILE ... or -i openehr FILE ... accepts openEHR JSON or YAML input as patient-bearing envelopes or composition sets.
  • openEHR input must carry a resolvable patient identifier in the payload or envelope; otherwise the conversion fails.
  • multiple openEHR files are supported when patient identity can be resolved; multi-patient input is grouped automatically before mapping.
  • The current openEHR CLI path is experimental and currently supports BFF and PXF output.

Dataset-JSON-specific options​

  • -idataset-json FILE ... or -i dataset-json FILE ... accepts one or more CDISC Dataset-JSON v1.1 SDTM domain files in .json or .json.gz form.
  • Exactly one DM dataset is required. Subject-level domains are grouped by USUBJID; no REDCap dictionary is used. A mapping file with source.profile: sdtm is optional for terminology enrichment.
  • --define-xml FILE is optional for Dataset-JSON and can supply authoritative nci:ExtCodeID identifiers and controlled-term displays.
  • datasetjson2bff, datasetjson2pxf, and datasetjson2omop are available. OMOP output also requires --ohdsi-db and --out-dir.
  • Input is currently processed in memory rather than streamed. See CDISC Dataset-JSON for mapped domains and current boundaries.

Dataset-XML-specific options​

  • -idataset-xml FILE ... or -i dataset-xml FILE ... accepts one or more CDISC Dataset-XML v1.0 SDTM domain files in .xml form.
  • --define-xml FILE is required and supplies the Define-XML v2.0/v2.1 metadata used to resolve each domain, column, order, label, and data type.
  • Exactly one DM dataset is required. Subject-level domains are grouped by USUBJID; a mapping file with source.profile: sdtm is optional for terminology enrichment.
  • datasetxml2bff, datasetxml2pxf, and datasetxml2omop are available. OMOP output also requires --ohdsi-db and --out-dir.
  • Input is processed in memory. See CDISC Dataset-XML for cross-file checks and current boundaries.

FHIR-specific options​

  • -ifhir FILE ... or -i fhir FILE ... accepts one or more FHIR R4 Bundle files in .json or .json.gz form.
  • Each Bundle must contain at least one Patient. Relative, absolute, and urn:uuid: resource references are resolved before resources are grouped by Patient.
  • mCODE 4.0 Bundles use the same input route. Canonical profile URLs are detected automatically; no mCODE-specific flag is required.
  • fhir2bff, fhir2pxf, and fhir2omop are available. Entity-aware BFF output can emit Specimen-derived biosamples; OMOP output also requires --ohdsi-db and --out-dir.
  • Input is processed in memory. See FHIR R4 for mapped resources and current boundaries.

General options​

  • --separator CHAR or --sep CHAR overrides the CSV delimiter. For .csv files the default remains ;.
  • --username NAME or -u NAME overrides the username stored in conversion metadata.
  • --default-vital-status ALIVE|DECEASED|UNKNOWN_STATUS sets the fallback subject.vitalStatus.status used for PXF output when no source-derived value is available. Default: ALIVE.
  • --source-info / --no-source-info controls whether raw source payloads are preserved in BFF info. Default: --source-info.
  • --log [FILE] writes the resolved request/configuration JSON. If no filename is provided, the default is convert-pheno-log.json in --out-dir.
  • --color / --no-color controls colored terminal output. Default: --color.
  • --test suppresses time-varying metadata so generated files are stable for comparisons.
  • --verbose or -v prints progress information.
  • --debug LEVEL prints the resolved internal request and extra debugging output. With LEVEL >= 2, it also prints a compact SQLite lookup summary (requests, cache hits, DB lookups, search resolution, and SQL timings).

More help​