5-Minute Quickstart
Use the command-line interface (CLI) to convert one small Phenopacket into Beacon v2 Models (BFF). This route needs no mapping file or external terminology database.
Using the graphical application? Follow Desktop: First conversion instead.
Prefer to try the tool without installing it locally? Use the Google Colab notebook.
1. Check the CLIβ
convert-pheno --version
If the command is unavailable, follow Download & Installation first.
2. Get the Example Inputβ
Download the example Phenopacket and save it as phenopacket.json.
The file contains a one-record Phenopacket collection with one phenotypic feature. You can view the PXF format details later; they are not required for this example.
3. Run the Conversionβ
convert-pheno -ipxf phenopacket.json -obff individuals.json
The command creates individuals.json in the current directory. The result contains the individual patient-1, its normalized sex ontology term, and the HP:0001250 phenotypic feature.
phenopacket.json was the source, -ipxf selected the input format, and -obff individuals.json selected the BFF output and filename.
4. Check the Resultβ
These fields appear in the converted record (other fields are omitted here):
{
"id": "patient-1",
"phenotypicFeatures": [
{
"featureType": {
"id": "HP:0001250",
"label": "Seizure"
}
}
],
"sex": {
"id": "NCIT:C16576",
"label": "Female"
}
}
The person identifier is retained from subject.id. The seizure term keeps its
ontology identifier, but moves from phenotypicFeatures[].type to Beacon's
phenotypicFeatures[].featureType. The source value FEMALE becomes an ontology
term with an identifier and label. The output file wraps the record in an array.
Open individuals.json, or inspect its first lines:
head -40 individuals.json
Where Next?β
- Command-Line Interface for the CLI model and commands matching your own input and target formats.
- Supported Formats for the complete format overview.
- CLI Options & Behavior for output directories, multiple entities, ontology search, and large OMOP exports.
- Mapping Files for an end-to-end REDCap mapping workflow.
- Regression fixtures for tested input and reference-output pairs across all implemented routes.