Package: phenopackets
Phenopacket schemaThis has been produced as part of theGA4GHClinical Phenotype Data Capture Workstreamand it merges the existingGA4GH metadata-schemaswork with a more focused model from thephenopacket-reference-implementation.This is a re-defined version of the original phenopacket with a more individual-centric approach. This new approach was taken in order to simplify the code required to represent and manipulate the data and also better represent this sort of data as it is in day to day use.DocumentationThe core documentation can be found atDocumentationThe documentation in this README is primarily for the users of the phenopacket-schema java library.Scope and PurposeThe goal of the phenopacket-schema is to define the phenotypic description of a patient/sample in the context of rare disease or cancer genomic diagnosis. It aims to provide sufficient and shareable information of the data outside of the EHR (Electronic Health Record) with the aim of enabling capturing of sufficient structured data at the point of care by a clinician or clinical geneticist for sharing with other labs or computational analysis of the data in clinical or research environments.The schema aims to define a common, limited set of data types which may be composed into more specialised types for data sharing between resources using an agreed upon common schema (as defined in base.proto).This common schema has been used to define the ‘Phenopacket’ which is a catch-all collection of data types, specifically focused on representing rare-disease or cancer samples for both initial data capture and analysis. The phenopacket is designed to be both human and machine-readable, and to inter-operate with the HL7 Fast Healthcare Interoperability Resources Specification (aka FHIR®).VersioningThe library uses semantic versioning. Seehttps://semver.orgfor details.Email listThere is a low-volume mailing list for announcements about phenopackets atphenopackets@groups.io. More information
about this list is available athttps://groups.io/g/phenopackets.UsageThe Phenopacket schema is defined usingProtobufwhich is“a language-neutral, platform-neutral extensible mechanism for serializing structured data”.  There are two ways to use this library, firstly using thePhenopacketas an exchange mechanism, secondly as a schema of basic types on which to build more specialist messages, yet allow for easy interoperability with other resources using the phenopackets schema.
The following sections describe how to achieve these two things.Include phenopackets into your projectJavapeople 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 inPythonis also straightforward:pipinstallphenopacketsExchanging Phenopackets directlyExamples 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 thePhenopacket.genesfield 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 formatsA Phenopacket can be transformed between the native binary format and JSON using theJsonFormatclass from theprotobuf-java-utillibrary. 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>pipinstallprotobufprotobuf-java-utilfor java andprotobuffor python contain simple utility methods to perform these transformations. Usage is shown here:// Transform a Phenopacket into JSONPhenopacketoriginal=TestExamples.rareDiseasePhenopacket();StringasJson=JsonFormat.printer().print(original);System.out.println(asJson);// Convert the JSON back to a PhenopacketPhenopacket.BuilderphenoPacketBuilder=Phenopacket.newBuilder();JsonFormat.parser().merge(jsonString,phenoPacketBuilder);PhenopacketfromJson=phenoPacketBuilder.build();// Convert the JSON into YAML (using Jackson)JsonNodejsonNodeTree=newObjectMapper().readTree(jsonString);StringyamlPhenopacket=newYAMLMapper().writeValueAsString(jsonNodeTree);// Convert the YAML back into JSON (using Jackson)JsonNodejsonNodeTree=newYAMLMapper().readTree(yamlString);StringjsonPhenopacket=newObjectMapper().writeValueAsString(jsonNodeTree);// And finally back into a Java objectPhenopacket.BuilderphenoPacketBuilder2=Phenopacket.newBuilder();JsonFormat.parser().merge(jsonPhenopacket,phenoPacketBuilder2);PhenopacketfromJson2=phenoPacketBuilder2.build();fromgoogle.protobuf.json_formatimportParse,MessageToJsonfromgoogle.protobuf.timestamp_pb2importTimestampfromphenopacketsimportPhenopacket,Individual,PhenotypicFeature,OntologyClass# Parsing phenopackets from jsonwithopen('file.json','r')asjsfile:phenopacket=Parse(Phenopacket(),text=jsfile.read())# Writing phenopackets to jsonwithopen('file.json','w')asjsfile: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 schemaThere is an example of how to do this included in themme.protofile. Here the Matchmaker Exchange (MME) API has been implemented using the phenopackets schema, defining custom messages as required, but re-using messages frombase.protowhere applicable. Using the above example, perhaps thePhenopacket.genesis 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 theGeneas a building block.Git SubmodulesThis repo usesgit submodulesto import theVRS protobufimplementation. You may need to use the following command after cloning/update
for things to build correctly:$gitsubmoduleupdate--init--recursiveBuildingThe project can be built using the awesomeTakari maven wrapperwhich requires no local maven installation. The only requirement for the build is to have a working java installation and network access.To do thiscdto the project root and run the wrapper scripts:$./mvnwcleaninstallor$./mvnw.cmdcleaninstallSign artefacts for releaseThere is arelease-sign-artifactsprofile forJavawhich can be triggered with the command$./mvnwcleaninstall-DperformRelease=trueThePythonartefacts are released by runningTest$bashdeploy-python.shrelease-testProduction$bashdeploy-python.shrelease-prodJava, Python and C++ artefactsBuilding the project will automatically compile Java, Python and C++ artefacts. The Java jar file can be directly used in any Java project. For Python or C++ the build artefacts can be found attarget/generated-sources/protobuf/pythonandtarget/generated-sources/protobuf/cppOther languages will need to compile the files insrc/main/prototo
their desired language. The protobuf developer site has examples on how
to do this, e.gGOorC#. Protobuf also supports ahost of other
languages.