Skip to main content

5-Minute Quickstart

Convert one small Phenopacket into Beacon v2 Models (BFF). This route needs no mapping file or external terminology database.

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