phenopackets/phenopacket-reference-implementation

Name: phenopacket-reference-implementation

Owner: PhenoPackets

Description: Reference java implementation for phenopackets

Created: 2016-02-19 03:38:54.0

Updated: 2017-04-20 21:04:55.0

Pushed: 2016-12-03 01:13:26.0

Homepage:

Size: 743

Language: Java

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Phenopackets/PXF Reference Implementation

This project provides a reference java implementation for the Phenotype eXchange Format (PXF). Jackson annotations are used to describe the mapping to the JSON serialization of PXF. We are also experimenting with generating the JSON Schema from the reference implementation.

See phenopacket-format repo and the src/test/resources package of this repo for examples of the serialised JSON and YAML formats. The phenopacket-format repo wiki contains more details on the project in general.

Including phenopackets-api in your code:

Maven

endency>
<groupId>org.phenopackets</groupId>
<artifactId>phenopackets-api</artifactId>
<version>${project.version}</version>
pendency>

Gradle

ile 'org.phenopackets:phenopackets-api:${project.version}'

Installing a development snapshot

When developing against an unreleased snapshot version of the API, you can use Maven to install it in your local m2 repository:

-Dgpg.skip install

Using it

Most of these examples have been taken from the test package. Check there for more thorough examples.

UML Diagram

This diagram shows the object model:

Reading a JSON/YAML file

oPacket phenoPacket = YamlReader.readFile("phenopacket.yaml");

Creating a Phenopacket

Where possible the Builder pattern is used to provide a fluent API for building objects and create immutable instances. The PhenoPacket class is immutable, although instances of classes from the org.phenopackets.api.model.condition and org.phenopackets.api.model.entity package are not.

oPacket phenoPacket = PhenoPacket.newBuilder()
            .id("PXF:000001")
            .title("Empty phenopacket")
            .build();

Entities

Entities refer to things such as individuals of an organism/people, variants or diseases. For example here is a new Person:

on person = new Person();
on.setId("person#1");
on.setLabel("Joe Bloggs");
on.setSex("M");

here is the disease Pfeiffer syndrome

ase disease = new Disease();
ase.setId("OMIM:101600");
ase.setLabel("Pfeiffer syndrome");
ase.setTypes(ImmutableList.of(
    OntologyClass.of("EFO:0000508", "genetic disorder")

Conditions

A Condition is usually defined with a phenotype, location, time of onset/offset the severity and the environment in which this condition was observed. A condition could simply be a phenotype - here is one from the HPO, with a negative type too (i.e. this was tested for and not observed).

otype phenotype = new Phenotype();
otype.setTypes(ImmutableList.of(
    OntologyClass.of("HP:0000272", "Malar flattening")

otype.setNegatedTypes(ImmutableList.of(
    OntologyClass.of("HP:0001249", "Intellectual disability")

or an occurrence of a disease

aseOccurrence diseaseOccurrence = new DiseaseOccurrence();
aseStage stage = new DiseaseStage();
e.setDescription("Childhood onset");
e.setTypes(ImmutableList.of(
    OntologyClass.of("HP:0011463", "Childhood onset")

aseOccurrence.setStage(stage);

and a disease phenotype

otype diseasePhenotype = new Phenotype();
asePhenotype.setTypes(ImmutableList.of(
                       OntologyClass.of("HP:0000272", "Malar flattening"),
                       OntologyClass.of("HP:0005347", "Cartilaginous trachea"),
                       OntologyClass.of("HP:0001249", "Intellectual disability"),
                       OntologyClass.of("HP:0005048", "Synostosis of carpal bones"),
                       OntologyClass.of("HP:0004440", "Coronal craniosynostosis"),
                       OntologyClass.of("HP:0001156", "Brachydactyly syndrome")

Typically an observation is accompanied with some kind of evidence attribution - here we have a journal

ence journalEvidence = new Evidence();
nalEvidence.setTypes(ImmutableList.of(OntologyClass.of("ECO:0000033", "TAS")));
ication pub = new Publication.Builder().setId("PMID:23455423").build();
nalEvidence.setSupportingPublications(ImmutableList.of(pub));

Associating Entities with Conditions

Entities can have associated Conditions.Entities and Conditions are linked by an Association. Associations are also immutable objects which use a Builder.

Here we're going to associate the phenotype with the person from the previous examples.

otypeAssociation patientPhenotypeAssociation = new PhenotypeAssociation.Builder(phenotype)
    .setEntity(person)
    .addEvidence(journalEvidence)
    .build();

and the Disease with the DiseaseAssociation

aseOccurrenceAssociation diseaseOccurrenceAssociation = new DiseaseOccurrenceAssociation.Builder(diseaseOccurrence)
    .setEntity(disease)
    .build();

and the typically observed phenotypes for this disease

notypeAssociation diseasePhenotypeAssociation = new PhenotypeAssociation.Builder(diseasePhenotype)
     .setEntity(disease)
     .build();

Adding Entities and Associations to a PhenoPacket

Using the API it s now trivial to create a phenopacket containing the person and their observed phenotype.

oPacket pk = PhenoPacket.newBuilder()
            .id(id)
            .title("Patient with a phenotype")
            .addPerson(person)
            .addPhenotypeAssociation(patientPhenotypeAssociation)
            .build();

or a disease as characterised by its associated phenotypes and its time of onset

oPacket pk = PhenoPacket.newBuilder()
            .id(id)
            .title("Description of a disease its phenotype and time of onset")
            .addDisease(disease)
            .addDiseaseOccurrenceAssociation(diseaseOccurrenceAssociation)
            .addPhenotypeAssociation(diseasePhenotypeAssociation)
            .build();

Writing to JSON/YAML

oPacket phenoPacket ...
ng yamlString = YamlGenerator.render(phenoPacket);