phenopackets 2.0.2.post1

Include phenopackets into your project

Java people can incorporate phenopackets into their code by importing the jar using maven:

<dependency>
    <groupId>org.phenopackets</groupId>
    <artifactId>phenopacket-schema</artifactId>
    <version>${phenopacket-schema.version}</version>
</dependency>

Using phenopackets in Python is also straightforward:

pip install phenopackets

Exchanging Phenopackets directly

Examples on how these can be used can be found in the test directory. There are no explicit relationships defined between fields in the phenopacket (apart from the Pedigree), so it is vital that resources exchanging phenopackets agree on what is valid and what the fields mean in relation to other fields in the phenopacket. For example the Phenopacket.genes field may be agreed upon as representing the genes for a gene panel in one context, or a set of candidate genes or perhaps a diagnosed causative gene.

JSON/YAML formats

A Phenopacket can be transformed between the native binary format and JSON using the JsonFormat class from the protobuf-java-util library. This will also need to be added to your pom.xml

<dependency>
    <groupId>com.google.protobuf</groupId>
    <artifactId>protobuf-java-util</artifactId>
    <version>${protobuf.version}</version>
</dependency>

pip install protobuf

protobuf-java-util for java and protobuf for python contain simple utility methods to perform these transformations. Usage is shown here:

// Transform a Phenopacket into JSON
Phenopacket original = TestExamples.rareDiseasePhenopacket();

String asJson = JsonFormat.printer().print(original);
System.out.println(asJson);

// Convert the JSON back to a Phenopacket
Phenopacket.Builder phenoPacketBuilder = Phenopacket.newBuilder();
JsonFormat.parser().merge(jsonString, phenoPacketBuilder);
Phenopacket fromJson = phenoPacketBuilder.build();

// Convert the JSON into YAML (using Jackson)
JsonNode jsonNodeTree = new ObjectMapper().readTree(jsonString);
String yamlPhenopacket = new YAMLMapper().writeValueAsString(jsonNodeTree);

// Convert the YAML back into JSON (using Jackson)
JsonNode jsonNodeTree = new YAMLMapper().readTree(yamlString);
String jsonPhenopacket = new ObjectMapper().writeValueAsString(jsonNodeTree);

// And finally back into a Java object
Phenopacket.Builder phenoPacketBuilder2 = Phenopacket.newBuilder();
JsonFormat.parser().merge(jsonPhenopacket, phenoPacketBuilder2);
Phenopacket fromJson2 = phenoPacketBuilder2.build();

from google.protobuf.json_format import Parse, MessageToJson
from google.protobuf.timestamp_pb2 import Timestamp
from phenopackets import Phenopacket, Individual, PhenotypicFeature, OntologyClass

# Parsing phenopackets from json
with open('file.json', 'r') as jsfile:
    phenopacket = Parse(Phenopacket(), text=jsfile.read())

# Writing phenopackets to json
with open('file.json', 'w') as jsfile:
    subject = Individual(id="Zaphod", sex="MALE", date_of_birth=Timestamp(seconds=-123456798))
    phenotypic_features = [PhenotypicFeature(type=OntologyClass(id="HG2G:00001", label="Hoopy")),
                           PhenotypicFeature(type=OntologyClass(id="HG2G:00002", label="Frood"))]

    phenopacket = Phenopacket(id="PPKT:1", subject=subject, phenotypic_features=phenotypic_features)

    json = MessageToJson(phenopacket)
    jsfile.write(json)

Building new messages from the schema

There is an example of how to do this included in the mme.proto file. Here the Matchmaker Exchange (MME) API has been implemented using the phenopackets schema, defining custom messages as required, but re-using messages from base.proto where applicable. Using the above example, perhaps the Phenopacket.genes is a problem as you wish to record not only the gene panels ordered, but also the candidate genes discovered in two separate fields. In this case, a new bespoke message could be created, using the Gene as a building block.