Skip to content

Phenopackets v2 (PXF)

PXF stands for Phenotype eXchange Format. Phenopackets v2 documentation.

Phenopackets v2

Figure extracted from www.ga4gh.org

Phenopackets organize information using top-level elements. Our software, Convert-Pheno, specifically processes data from the Phenopacket element, serialized in PXF format.

Convert-Pheno supports PXF in both directions:

  • as input, for conversions such as pxf2bff, pxf2csv, and pxf2jsonf
  • as output, for conversions such as bff2pxf, omop2pxf, redcap2pxf, csv2pxf, and cdisc2pxf
Browsing PXF JSON data

You can browse a public Phenopackets v2 file with onf of teh following JSON viewers:

PXF As Input PXF

When using the convert-pheno command-line interface, simply ensure the correct syntax is provided.

convert-pheno -ipxf ipxf.json -obff individuals.json
About JSON data structure in I/O files

Note that the input -ipxf file can consist of one individual (one JSON object) or a list of individuals (a JSON array of objects). The output --obff file will replicate the data structure of the input file.

About biosamples and interpretations

In the individuals-only -obff individuals.json path, convert-pheno still emits only the Beacon individuals entity. If a PXF input also contains biosamples, the CLI warns and preserves them under info.phenopacket.biosamples for backward compatibility.

If you want entity-aware BFF output, use entity mode instead:

convert-pheno -ipxf pxf.json -obff --entities biosamples --out-dir out/
convert-pheno -ipxf pxf.json -obff --entities individuals biosamples --out-dir out/
convert-pheno -ipxf pxf.json -obff --entities individuals biosamples datasets cohorts --out-dir out/

You can also override the biosample filename:

convert-pheno -ipxf pxf.json -obff --entities individuals biosamples --out-dir out/ --out-name biosamples=samples.json

In entity mode, biosamples are mapped directly from the PXF input, while datasets and cohorts are synthesized from the normalized individuals collection.

interpretations are still preserved under info.phenopacket because they are not yet exposed as a first-class Beacon output entity in the CLI.

About vitalStatus preservation and fallback

When converting PXF to BFF, subject.vitalStatus is preserved under info.phenopacket.vitalStatus.

If that BFF record is later converted back to PXF, convert-pheno restores the preserved vitalStatus. If no source vitalStatus is available, convert-pheno falls back to ALIVE by default, or to the value provided with --default-vital-status:

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

The module interface takes one flat payload. Unlike the HTTP API, module arguments are not split into input, output, and options.

use Convert::Pheno;

my $payload = {
    method => 'pxf2bff',
    data   => $my_pxf_json_data,
    test   => 1,
};

my $convert = Convert::Pheno->new($payload);
my $bff     = $convert->pxf2bff;

from convertpheno import PythonBinding

payload = {
    "method": "pxf2bff",
    "data": my_pxf_json_data,
    "test": 1,
}

bff = PythonBinding(payload).convert_pheno()

Send a POST request to the API URL (see more info here) with a small payload like:

{
  "conversion": "pxf2bff",
  "input": {
    "data": {
      "phenopacket": {
        "id": "P0007500",
        "subject": {
          "id": "P0007500",
          "sex": "FEMALE"
        }
      }
    }
  },
  "output": {
    "entities": ["individuals"]
  }
}

Successful API responses wrap the conversion result under data.

PXF As Output

PXF can also be emitted as an output format. Common routes include:

  • bff2pxf
  • omop2pxf
  • redcap2pxf
  • csv2pxf
  • cdisc2pxf

Examples:

convert-pheno -ibff individuals.json -opxf phenopackets.json
convert-pheno -iomop omop.sql.gz -opxf phenopackets.json.gz --ohdsi-db
convert-pheno -icsv clinical.csv --mapping-file clinical.yaml -opxf phenopackets.json

Please find below examples of data:

{
   "diseases" : [],
   "id" : "phenopacket_id.AUNb6vNX1",
   "measurements" : [
      {
         "assay" : {
            "id" : "LOINC:35925-4",
            "label" : "BMI"
         },
         "value" : {
            "quantity" : {
               "unit" : {
                  "id" : "NCIT:C49671",
                  "label" : "Kilogram per Square Meter"
               },
               "value" : 26.63838307
            }
         }
      },
      {
         "assay" : {
            "id" : "LOINC:3141-9",
            "label" : "Weight"
         },
         "value" : {
            "quantity" : {
               "unit" : {
                  "id" : "NCIT:C28252",
                  "label" : "Kilogram"
               },
               "value" : 85.6358
            }
         }
      },
      {
         "assay" : {
            "id" : "LOINC:8308-9",
            "label" : "Height-standing"
         },
         "value" : {
            "quantity" : {
               "unit" : {
                  "id" : "NCIT:C49668",
                  "label" : "Centimeter"
               },
               "value" : 179.2973
            }
         }
      }
   ],
   "medicalActions" : [
      {
         "procedure" : {
            "code" : {
               "id" : "OPCS4:L46.3",
               "label" : "OPCS(v4-0.0):Ligation of visceral branch of abdominal aorta NEC"
            },
            "performed" : {
               "timestamp" : "1900-01-01T00:00:00Z"
            }
         }
      }
   ],
   "metaData" : null,
   "subject" : {
      "id" : "HG00096",
      "sex" : "MALE",
      "vitalStatus" : {
         "status" : "ALIVE"
      }
   }
}

{
  "ethnicity": {
    "id": "NCIT:C42331",
    "label": "African"
  },
  "id": "HG00096",
  "info": {
    "eid": "fake1"
  },
  "interventionsOrProcedures": [
    {
      "procedureCode": {
        "id": "OPCS4:L46.3",
        "label": "OPCS(v4-0.0):Ligation of visceral branch of abdominal aorta NEC"
      }
    }
  ],
  "measures": [
    {
      "assayCode": {
        "id": "LOINC:35925-4",
        "label": "BMI"
      },
      "date": "2021-09-24",
      "measurementValue": {
        "quantity": {
          "unit": {
            "id": "NCIT:C49671",
            "label": "Kilogram per Square Meter"
          },
          "value": 26.63838307
        }
      }
    },
    {
      "assayCode": {
        "id": "LOINC:3141-9",
        "label": "Weight"
      },
      "date": "2021-09-24",
      "measurementValue": {
        "quantity": {
          "unit": {
            "id": "NCIT:C28252",
            "label": "Kilogram"
          },
          "value": 85.6358
        }
      }
    },
    {
      "assayCode": {
        "id": "LOINC:8308-9",
        "label": "Height-standing"
      },
      "date": "2021-09-24",
      "measurementValue": {
        "quantity": {
          "unit": {
            "id": "NCIT:C49668",
            "label": "Centimeter"
          },
          "value": 179.2973
        }
      }
    }
  ],
  "sex": {
    "id": "NCIT:C20197",
    "label": "male"
  }
}