Welcome to the documentation for pyrophen!
The goal of the pyrophen is to generate a FHIR Code system for representing the Human Phenotype Ontology (HPO). Pyrophen can create a FHIR HPO codeset in XML or JSON format.
pyrophen is used by
the HPO build system to generate the hp_fhir.xml file with every release, and
end users do not need to use or know anything about pyrophen.
However,
we have made the pyrophen code base and
this documentation public in the interest of transparency and to elicit feedback from
interested parties.
Introduction to pyrophen
What is FHIR?
The standards development organization Health Level Seven (HL7) is a non-profit ANSI-accredited standards development organization dedicated to providing standards and solutions for global health data interoperability.
HL7 develops Fast Healthcare Interoperability Resource (FHIR) is a a standard describing data formats and elements (known as “resources”) and an application programming interface (API) for exchanging electronic health records (EHR) (Wikipedia entry). The NIH is supporting FHIR for research user.
It is here that we see the major current use case for the HPO FHIR Codeset.
FHIR provides a set of modular components called “Resources” that can easily be assembled into working systems that solve real world clinical and administrative problems. FHIR enables access to data distributed across systems, databases, and devices in real time, similar to the World-Wide Web.
What is a FHIR Code system?
A FHIR code system declares the existence of and describes a code system or code system supplement and its key properties, and optionally defines a part or all of its content. Also known as Ontology, Terminology, or Enumeration
What is a FHIR Value set?
A FHIR value set specifies a set of codes drawn from one or more code systems, intended for use in a particular context. Value sets link between CodeSystem definitions and their use in coded elements.
What is the Human Phenotype Ontology (HPO)
The Human Phenotype Ontology (HPO, HPO) was launched in 2008 to provide a comprehensive logical standard to describe and computationally analyze phenotypic abnormalities found in human disease. The HPO is now a worldwide standard for phenotype exchange and is used by many software tools for computational phenotype analysis. The HPO provides a standardized vocabulary of phenotypic abnormalities encountered in human disease. Each term in the HPO describes a phenotypic abnormality, such as Atrial septal defect. The HPO is currently being developed using the medical literature, Orphanet, DECIPHER, and OMIM. HPO currently contains over 15,000 terms and over 200,000 annotations to hereditary diseases.
What is the purpose of this codeset?
The codeset that is generated by pyrophen provides a specified set of HPO codes for use in FHIR coded elements.
Representation of terms in OBO and FHIR XML
In this example, we show how the HPO term for Decreased circulating IgG4 level is represented in OBO and in FHIR XML format.
OBO
The Open Biological and Biomedical Ontology (OBO) format is a simple format originally designed to make it easier for biologists to author ontologies. The HPO is natively authored in the more sophisticated OWL format, but is available in OBO and JSON formats as well.
[Term]
id: HP:0032138
name: Decreased circulating IgG4 level
def: "A reduction in immunoglobulin levels of the IgG4 subclass in the blood circulation." [PMID:26929632]
synonym: "Decreased IgG4 level in blood" EXACT []
is_a: HP:0032135 ! Decreased circulating IgG subclass level
property_value: http://purl.org/dc/elements/1.1/date 2018-11-22T14:29:39Z xsd:dateTime
created_by: peter
This stanza specifies the identifier (HP:0032138), the name, i.e., label (Decreased circulating IgG4 level),
the definition, a synonym, and the parent (HP:0032135 ! Decreased circulating IgG subclass level).
The term is represented as follows in the FHIR XML.
<concept>
<code value="HP:0032138"></code>
<display value="Decreased circulating IgG4 level"></display>
<definition value="A reduction in immunoglobulin levels of the IgG4 subclass
in the blood circulation."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0032135"></valueCode>
</property>
</concept>
The synonym is represented using the desgination element with reference to the
SNOMED CT code for Synonym. In general, a list of synonyms may be used.
The parentage is represented by a property element. In general, a term may have more than
one parent, in which case multiple property elements are used.
Example (XML)
pyrophen outputs the codeset in XML or JSON format. See Example (JSON) for JSON.
The test class HpoFhirTerminologyApplicationTests writes a temporary file with the CodeSystem created for a small excerpt of the HPO located
in src/test/resources/hp_head.obo.
This is the XML file that is produced.
<CodeSystem xmlns="http://hl7.org/fhir">
<id value="hpo"></id>
<url value="http://purl.obolibrary.org/obo/hp.fhir"></url>
<version value="http://purl.obolibrary.org/obo/hp/releases/2017-04-13/hp.owl"></version>
<name value="HPO"></name>
<title value="Human Phenotype Ontology Coding"></title>
<status value="active"></status>
<experimental value="false"></experimental>
<date value="2021-04-18T14:30:10-04:00"></date>
<publisher value="The Human Phenotype Ontology"></publisher>
<contact>
<name value="Peter N. Robinson"></name>
</contact>
<description value="A FHIR code system representation of the Human Phenotype Ontology."></description>
<purpose value="To provide a standardized vocabulary of human phenotypes encountered in human disease in a FHIR context."></purpose>
<copyright value="https://hpo.jax.org/app/license"></copyright>
<concept>
<code value="HP:0000001"></code>
<display value="All"></display>
</concept>
<concept>
<code value="HP:0040282"></code>
<display value="Frequent"></display>
<definition value="Present in 30% to 79% of the cases."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0040279"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0040281"></code>
<display value="Very frequent"></display>
<definition value="Present in 80% to 99% of the cases."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0040279"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0040284"></code>
<display value="Very rare"></display>
<definition value="Present in 1% to 4% of the cases."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0040279"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0040283"></code>
<display value="Occasional"></display>
<definition value="Present in 5% to 29% of the cases."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0040279"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0040280"></code>
<display value="Obligate"></display>
<definition value="Always present, i.e. in 100% of the cases."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0040279"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0100886"></code>
<display value="Abnormality of globe location"></display>
<definition value="An abnormality in the placement of the ocular globe (eyeball)."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0012374"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0012374"></code>
<display value="Abnormal globe morphology"></display>
<definition value="An anomaly of the eyeball."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0012372"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0040279"></code>
<display value="Frequency"></display>
<definition value="Class to represent frequency of phenotypic abnormalities within a patient cohort."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0000001"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0100887"></code>
<display value="Abnormality of globe size"></display>
<definition value="An abnormality in the size of the ocular globe (eyeball)."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0012374"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0000528"></code>
<display value="Anophthalmia"></display>
<definition value="Absence of the globe or eyeball."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0100887"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0040285"></code>
<display value="Excluded"></display>
<definition value="Present in 0% of the cases."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0040279"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0012372"></code>
<display value="Abnormal eye morphology"></display>
<definition value="A structural anomaly of the eye."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0000478"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0012373"></code>
<display value="Abnormal eye physiology"></display>
<definition value="A functional anomaly of the eye."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0000478"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0000118"></code>
<display value="Phenotypic abnormality"></display>
<definition value="A phenotypic abnormality."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0000001"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0000007"></code>
<display value="Autosomal recessive inheritance"></display>
<definition value="A mode of inheritance that is observed for traits related to a gene encoded on one of the autosomes (i.e., the human chromosomes 1-22) in which a trait manifests in homozygotes. In the context of medical genetics, autosomal recessive disorders manifest in homozygotes (with two copies of the mutant allele) or compound heterozygotes (whereby each copy of a gene has a distinct mutant allele)."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0000005"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0000568"></code>
<display value="Microphthalmia"></display>
<definition value="A developmental anomaly characterized by abnormal smallness of one or both eyes."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0100887"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0007686"></code>
<display value="Abnormal pupillary function"></display>
<definition value="A functional abnormality of the pupil."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0012373"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0000006"></code>
<display value="Autosomal dominant inheritance"></display>
<definition value="A mode of inheritance that is observed for traits related to a gene encoded on one of the autosomes (i.e., the human chromosomes 1-22) in which a trait manifests in heterozygotes. In the context of medical genetics, an autosomal dominant disorder is caused when a single copy of the mutant allele is present. Males and females are affected equally, and can both transmit the disorder with a risk of 50% for each child of inheriting the mutant allele."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0000005"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0000478"></code>
<display value="Abnormality of the eye"></display>
<definition value="Any abnormality of the eye, including location, spacing, and intraocular abnormalities."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0000118"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0000632"></code>
<display value="Lacrimation abnormality"></display>
<definition value="Abnormality of tear production."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0012373"></valueCode>
</property>
</concept>
<concept>
<code value="HP:0000005"></code>
<display value="Mode of inheritance"></display>
<definition value="The pattern in which a particular genetic trait or disorder is passed from one generation to the next."></definition>
<property>
<code value="parent"></code>
<valueCode value="HP:0000001"></valueCode>
</property>
</concept>
</CodeSystem>
Example (JSON)
pyrophen outputs the codeset in XML or JSON format. See Example (XML) for XML.
The test class HpoFhirTerminologyApplicationTests writes a temporary file with the CodeSystem created for a small excerpt of the HPO located
in src/test/resources/hp_head.obo.
This is the JSON file that is produced.
{
"resourceType": "CodeSystem",
"id": "hpo",
"url": "http://purl.obolibrary.org/obo/hp.fhir",
"version": "http://purl.obolibrary.org/obo/hp/releases/2017-04-13/hp.owl",
"name": "HPO",
"title": "Human Phenotype Ontology Coding",
"status": "active",
"experimental": false,
"date": "2021-05-03T08:04:39-04:00",
"publisher": "The Human Phenotype Ontology",
"contact": [ {
"name": "Peter N. Robinson"
} ],
"description": "A FHIR code system representation of the Human Phenotype Ontology.",
"purpose": "To provide a standardized vocabulary of human phenotypes encountered in human disease in a FHIR context.",
"copyright": "https://hpo.jax.org/app/license",
"concept": [ {
"code": "HP:0000001",
"display": "All"
}, {
"code": "HP:0040282",
"display": "Frequent",
"definition": "Present in 30% to 79% of the cases.",
"property": [ {
"code": "parent",
"valueCode": "HP:0040279"
} ]
}, {
"code": "HP:0040281",
"display": "Very frequent",
"definition": "Present in 80% to 99% of the cases.",
"property": [ {
"code": "parent",
"valueCode": "HP:0040279"
} ]
}, {
"code": "HP:0040284",
"display": "Very rare",
"definition": "Present in 1% to 4% of the cases.",
"property": [ {
"code": "parent",
"valueCode": "HP:0040279"
} ]
}, {
"code": "HP:0040280",
"display": "Obligate",
"definition": "Always present, i.e. in 100% of the cases.",
"property": [ {
"code": "parent",
"valueCode": "HP:0040279"
} ]
}, {
"code": "HP:0100886",
"display": "Abnormality of globe location",
"definition": "An abnormality in the placement of the ocular globe (eyeball).",
"property": [ {
"code": "parent",
"valueCode": "HP:0012374"
} ]
}, {
"code": "HP:0012374",
"display": "Abnormal globe morphology",
"definition": "An anomaly of the eyeball.",
"property": [ {
"code": "parent",
"valueCode": "HP:0012372"
} ]
}, {
"code": "HP:0040279",
"display": "Frequency",
"definition": "Class to represent frequency of phenotypic abnormalities within a patient cohort.",
"property": [ {
"code": "parent",
"valueCode": "HP:0000001"
} ]
}, {
"code": "HP:0100887",
"display": "Abnormality of globe size",
"definition": "An abnormality in the size of the ocular globe (eyeball).",
"property": [ {
"code": "parent",
"valueCode": "HP:0012374"
} ]
}, {
"code": "HP:0000528",
"display": "Anophthalmia",
"definition": "Absence of the globe or eyeball.",
"property": [ {
"code": "parent",
"valueCode": "HP:0100887"
} ]
}, {
"code": "HP:0040285",
"display": "Excluded",
"definition": "Present in 0% of the cases.",
"property": [ {
"code": "parent",
"valueCode": "HP:0040279"
} ]
}, {
"code": "HP:0012372",
"display": "Abnormal eye morphology",
"definition": "A structural anomaly of the eye.",
"property": [ {
"code": "parent",
"valueCode": "HP:0000478"
} ]
}, {
"code": "HP:0012373",
"display": "Abnormal eye physiology",
"definition": "A functional anomaly of the eye.",
"property": [ {
"code": "parent",
"valueCode": "HP:0000478"
} ]
}, {
"code": "HP:0000118",
"display": "Phenotypic abnormality",
"definition": "A phenotypic abnormality.",
"property": [ {
"code": "parent",
"valueCode": "HP:0000001"
} ]
}, {
"code": "HP:0000007",
"display": "Autosomal recessive inheritance",
"definition": "A mode of inheritance that is observed for traits related to a gene encoded on one of the autosomes (i.e., the human chromosomes 1-22) in which a trait manifests in homozygotes. In the context of medical genetics, autosomal recessive disorders manifest in homozygotes (with two copies of the mutant allele) or compound heterozygotes (whereby each copy of a gene has a distinct mutant allele).",
"property": [ {
"code": "parent",
"valueCode": "HP:0000005"
} ]
}, {
"code": "HP:0000568",
"display": "Microphthalmia",
"definition": "A developmental anomaly characterized by abnormal smallness of one or both eyes.",
"property": [ {
"code": "parent",
"valueCode": "HP:0100887"
} ]
}, {
"code": "HP:0007686",
"display": "Abnormal pupillary function",
"definition": "A functional abnormality of the pupil.",
"property": [ {
"code": "parent",
"valueCode": "HP:0012373"
} ]
}, {
"code": "HP:0000006",
"display": "Autosomal dominant inheritance",
"definition": "A mode of inheritance that is observed for traits related to a gene encoded on one of the autosomes (i.e., the human chromosomes 1-22) in which a trait manifests in heterozygotes. In the context of medical genetics, an autosomal dominant disorder is caused when a single copy of the mutant allele is present. Males and females are affected equally, and can both transmit the disorder with a risk of 50% for each child of inheriting the mutant allele.",
"property": [ {
"code": "parent",
"valueCode": "HP:0000005"
} ]
}, {
"code": "HP:0000478",
"display": "Abnormality of the eye",
"definition": "Any abnormality of the eye, including location, spacing, and intraocular abnormalities.",
"property": [ {
"code": "parent",
"valueCode": "HP:0000118"
} ]
}, {
"code": "HP:0000632",
"display": "Lacrimation abnormality",
"definition": "Abnormality of tear production.",
"property": [ {
"code": "parent",
"valueCode": "HP:0012373"
} ]
}, {
"code": "HP:0000005",
"display": "Mode of inheritance",
"definition": "The pattern in which a particular genetic trait or disorder is passed from one generation to the next.",
"property": [ {
"code": "parent",
"valueCode": "HP:0000001"
} ]
} ]
}
Building and Running pyrophen
pyrophen is a Java application that can be built using Java version 11 or later. pyrophen makes use of the Spring framework. Additionally, maven is required to build pyrophen.
Building pyrophen
Clone pyrophen from its GitHub repository.
git clone https://github.com/monarch-initiative/pyrophen
Alternatively, you can download the source code from the repository https://github.com/monarch-initiative/pyrophen.
Change into the directory and build.
cd pyrophen
mvn package
This will create an executable jar file in a subdirectory called target. To test the build, run
the code without arguments. You should see something like the following.
java -jar target/pyrophen.jar
2021-04-17 12:55:50.287 INFO 31254 --- [ main] o.s.nativex.NativeListener : This application is bootstrapped with code generated with Spring AOT
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v2.4.4)
2021-04-17 12:55:50.386 INFO 31254 --- [ main] org.hpo.fhir.hpofhirterminology.CliMain : Starting CliMain v0.0.1-SNAPSHOT using Java 14.0.1 on MLI-Robinson with PID 31254 (/Users/robinp/IdeaProjects/pyrophen/target/pyrophen.jar started by robinp in /Users/robinp/IdeaProjects/pyrophen)
2021-04-17 12:55:50.387 INFO 31254 --- [ main] org.hpo.fhir.hpofhirterminology.CliMain : No active profile set, falling back to default profiles: default
2021-04-17 12:55:51.145 INFO 31254 --- [ main] org.hpo.fhir.hpofhirterminology.CliMain : Started CliMain in 1.219 seconds (JVM running for 1.815)
Missing required option: '--hpo=<pathToHpo>'
Usage: fhir [--format=<outputFormat>] --hpo=<pathToHpo> [--out=<outfileName>]
--format=<outputFormat>
format of output file (json [default], xml)
--hpo=<pathToHpo> path to HPO json file
--out=<outfileName> name/path of outfile
Running pyrophen
To run pyrophen, you will need to have a copy of the hp.json file. The latest version
can be obtained from the
HPO GitHub repository.
The pyrophen app gets the path to this file via the ``--hpo argument. Additionally, you can
set the name/path of the output XML file via the --out argument (the default is hp_fhir.json).
java -jar pyrophen.jar --hpo /some/path/hp.json [--out myxmlfile.json]