Phenopackets v2

PXF stands for Phenotype eXchange Format. Pheno-Ranker reads Phenopackets v2 serialized as JSON or YAML without requiring a custom configuration.

RoleNative input

Accepted inputPhenopacket JSON/YAML

ConfigurationBuilt in

Best forPhenopackets v2 records

Top-level Phenopacket fields and representative nested clinical content used for comparison.

Phenopackets organize clinical information into top-level elements such as the subject, phenotypic features, diseases, measurements, medical actions, and interpretations. Pheno-Ranker compares the categorical content within those elements.

Browse an example Phenopacket

You can inspect a public Phenopackets v2 record with JSON Hero or Datasette.

PXF As Input

The examples below use a simulated cohort of 100 Phenopackets. Download it once:

curl -L https://raw.githubusercontent.com/CNAG-Biomedical-Informatics/pheno-ranker/main/share/ex/pxf_random_100.json -o pxf.json

Nested PXF data

No manual transposition is required. Pheno-Ranker automatically handles nested arrays, including PXF-specific genomic interpretations, before comparison.

Cohort mode

Compare every Phenopacket against every other Phenopacket:

pheno-ranker -r pxf.json

The command creates matrix.txt, an N x N pairwise comparison matrix. To compare only selected top-level elements, use --include-terms:

pheno-ranker -r pxf.json --include-terms phenotypicFeatures diseases

Continue with Cohort Mode to choose a metric, create sparse output, or export a graph.

Patient mode

Patient mode requires one target Phenopacket. You can provide your own target or extract one record from the downloaded cohort:

pheno-ranker -r pxf.json --patients-of-interest Phenopacket_1

This creates Phenopacket_1.json. Rank the reference cohort against it:

pheno-ranker -r pxf.json -t Phenopacket_1.json

The command creates rank.txt, ordered by Hamming distance by default. Continue with Patient Mode to interpret the ranking columns or select Jaccard similarity.

Automatic Nested-Array Handling

From v1.08 onward, array order does not prevent equivalent nested PXF content from matching. This applies to structures such as diagnostic markers, disease stages, typed quantities, and treatment dose intervals. See the algorithm description for the general canonicalization method.

PXF-specific handling of genomic interpretations

Genomic interpretations require one additional PXF-specific step. Their source objects can contain patient-specific values in id and subjectOrBiosampleId. If those values became part of a comparison key, the same disease or gene would appear different in every patient.

Pheno-Ranker therefore organizes each interpretation by the diagnosed disease identifier and each genomic interpretation by its gene identifier. For example, an interpretation containing disease OMIM:148600, gene HGNC:25662, status CAUSATIVE, and progress status SOLVED produces comparison keys such as:

interpretations.OMIM:148600.genomicInterpretations.HGNC:25662.interpretationStatus.CAUSATIVE
interpretations.OMIM:148600.genomicInterpretations.HGNC:25662.variantInterpretation.variationDescriptor.geneContext.symbol.AAGAB
interpretations.OMIM:148600.progressStatus.SOLVED

The patient-specific identifiers are not used in these keys, allowing the same disease and gene content to match across Phenopackets. This transformation is automatic when interpretations is included in the comparison.