Creating Phenopackets

Google’s Protocol Buffer (protobuf) framework automatically generates Java bindings for building and working with Phenopackets. However, the code can be unwieldy. Additionally, many users of the phenopacket framework will want to use a recommended set of ontology terms for specific kinds of data. Phenopacket-tools library provides terms and constants that are more convenient to use than manually creating the equivalent message.

This section exemplifies usage of PhenotypicFeatureBuilder, one of many builders provided by the org.phenopackets.phenopackettools.builder module.

phenopacket-tools builder pattern

In this example, let’s imagine we want to create a PhenotypicFeature element to denote that severe weakness of the left triceps muscle was observed in a patient at the age of 11 years and 4 months. First, let us code this using the Phenopacket code that is automatically generated by the protobuf framework.

OntologyClass tricepsWeakness = OntologyClass.newBuilder()
            .setId("HP:0031108")
            .setLabel("Triceps weakness")
            .build();
OntologyClass left = OntologyClass.newBuilder()
            .setId("HP:0012835")
            .setLabel("Left")
            .build();
OntologyClass severe = OntologyClass.newBuilder()
            .setId("HP:0012828")
            .setLabel("Severe")
            .build();
Age iso8601duration = Age.newBuilder().setIso8601Duration("P11Y4M").build();
TimeElement ageElement = TimeElement.newBuilder().setAge(iso8601duration)
            .setAge(iso8601duration)
            .build();
PhenotypicFeature phenotypicFeature = PhenotypicFeature.newBuilder()
            .setType(tricepsWeakness)
            .setOnset(ageElement)
            .setSeverity(severe)
            .addModifiers(left)
            .build();

The following code block uses functions from the phenopacket-tools library to simplify the creation of this PhenotypicFeature element.

PhenotypicFeature phenotypicFeature2 = PhenotypicFeatureBuilder.builder("HP:0031108", "Triceps weakness")
            .addModifier(severe())
            .addModifier(left())
            .onset(TimeElements.age("P11Y4M"))
            .build();

Both code snippets generate identical phenopacket code.

{
    "type": {
        "id": "HP:0031108",
        "label": "Triceps weakness"
    },
    "severity": {
        "id": "HP:0012828",
        "label": "Severe"
    },
    "modifiers": [{
        "id": "HP:0012835",
        "label": "Left"
    }],
    "onset": {
        "age": {
            "iso8601duration": "P11Y4M"
        }
    }
}

Creating Phenopackets

phenopacket-tools builder pattern

See also