Skip to main content

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.

What the flags mean

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?​