Working with Phenopackets in Java

Here we provide some guidance on how to work with Phenopackets in Java. The sections on Java Build, Exporting and Importing Phenopackets provide general guidance about using Java to work with phenopackets. The following sections provide a few examples of how to build various elements of Phenopackets. Finally, we present the full Java code used to build each of the examples for rare disease and cancer.

• including phenopackets in Java projects
• Phenopacket File I/O in Java
• evidence
• timestamp
• duration

The Java code

We show some Java code that demonstrates the basic methodology for building a Phenopacket. We have put the entire code into one function for didactic purposes, but real-life code might be more structured. We do define one auxialliary function

/** convenience function to help creating OntologyClass objects. */
 public static OntologyClass ontologyClass(String id, String label) {
     return OntologyClass.newBuilder()
             .setId(id)
             .setLabel(label)
             .build();
 }

With this, we present a function that creates a Phenopacket that represents the case report described above

public Phenopacket spherocytosisExample() {
      final String PROBAND_ID = "PROBAND#1";
      PhenotypicFeature spherocytosis = PhenotypicFeature.newBuilder()
              .setType(ontologyClass("HP:0004444", "Spherocytosis"))
              .setClassOfOnset(ontologyClass("HP:0011463", "Childhood onset"))
              .build();
      PhenotypicFeature jaundice = PhenotypicFeature.newBuilder()
              .setType(ontologyClass("HP:0000952", "Jaundice"))
              .setClassOfOnset(ontologyClass("HP:0011463", "Childhood onset"))
              .build();
      PhenotypicFeature splenomegaly = PhenotypicFeature.newBuilder()
              .setType(ontologyClass("HP:0001744", "Splenomegaly"))
              .setClassOfOnset(ontologyClass("HP:0011463", "Childhood onset"))
              .build();
      PhenotypicFeature notHepatomegaly = PhenotypicFeature.newBuilder()
              .setType(ontologyClass("HP:0002240", "Hepatomegaly"))
              .setExcluded(true)
              .build();
      PhenotypicFeature reticulocytosis = PhenotypicFeature.newBuilder()
              .setType(ontologyClass("HP:0001923", "Reticulocytosis"))
              .build();

      VcfAllele vcfAllele = VcfAllele.newBuilder()
              .setGenomeAssembly("GRCh37")
              .setChr("8")
              .setPos(41519441)
              .setRef("G")
              .setAlt("A")
              .build();

      Variant ANK1_variant = Variant.newBuilder()
              .setVcfAllele(vcfAllele)
              .setZygosity(ontologyClass("GENO:0000135", "heterozygous"))
              .build();

      Individual proband = Individual.newBuilder()
              .setSex(Sex.FEMALE)
              .setId(PROBAND_ID)
              .setAgeAtCollection(Age.newBuilder().setAge("P27Y3M").build())
              .build();

      MetaData metaData = MetaData.newBuilder()
              .addResources(Resource.newBuilder()
                      .setId("hp")
                      .setName("human phenotype ontology")
                      .setNamespacePrefix("HP")
                      .setIriPrefix("http://purl.obolibrary.org/obo/HP_")
                      .setUrl("http://purl.obolibrary.org/obo/hp.owl")
                      .setVersion("2018-03-08")
                      .build())
              .addResources(Resource.newBuilder()
                      .setId("geno")
                      .setName("Genotype Ontology")
                      .setNamespacePrefix("GENO")
                      .setIriPrefix("http://purl.obolibrary.org/obo/GENO_")
                      .setUrl("http://purl.obolibrary.org/obo/geno.owl")
                      .setVersion("19-03-2018")
                      .build())
              .setCreatedBy("Example clinician")
              .build();

      return Phenopacket.newBuilder()
              .setSubject(proband)
              .addPhenotypicFeatures(spherocytosis)
              .addPhenotypicFeatures(jaundice)
              .addPhenotypicFeatures(splenomegaly)
              .addPhenotypicFeatures(notHepatomegaly)
              .addPhenotypicFeatures(reticulocytosis)
              .addAllVariants(ImmutableList.of(ANK1_variant))
              .setMetaData(metaData)
              .build();
  }

Writing a Phenopacket in protobuf format

Messages can be written in binary format using the native protobuf encoding. While this is useful for machine-to-machine

communication due to low latency and overhead of serialisation it is not human-readable. We refer the reader to the official documentation on this topic, but will briefly give an example of writing to an OutputStream here.

Path path = Paths.get("/path/to/file");
try (OutputStream outputStream = Files.newOutputStream(path)) {
    Phenopacket phenoPacket = new PhenoPacketExample().spherocytosisExample();
    phenoPacket.writeTo(outputStream);
} catch (IOException e) {
    e.printStackTrace();
}

// read it back again
try (InputStream inputStream = Files.newInputStream(path)) {
    Phenopacket deserialised = Phenopacket.parseFrom(inputStream);
} catch (IOException e) {
    e.printStackTrace();
}

JSON export

In many situations it may be desirable to export the Phenopacket as JSON. This is easy with the following commands:

First add the protobuf-java-util dependency to your Maven POM.xml

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

Then you can use it to print out JSON using the JsonFormat class.

Phenopacket p = spherocytosisExample();
try {
    String jsonString = JsonFormat.printer().includingDefaultValueFields().print(p);
    System.out.println(jsonString);
} catch (Exception e) {
    e.printStackTrace();
}