{"id":18407234,"url":"https://github.com/octri/fhir2hpo","last_synced_at":"2026-02-17T15:01:17.771Z","repository":{"id":55645390,"uuid":"134331832","full_name":"OCTRI/fhir2hpo","owner":"OCTRI","description":"Library for converting FHIR messages to HPO","archived":false,"fork":false,"pushed_at":"2021-01-12T20:00:25.000Z","size":2181,"stargazers_count":7,"open_issues_count":2,"forks_count":2,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-10-08T06:58:22.845Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OCTRI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-21T22:31:28.000Z","updated_at":"2023-05-13T07:01:40.000Z","dependencies_parsed_at":"2022-08-15T05:20:54.048Z","dependency_job_id":null,"html_url":"https://github.com/OCTRI/fhir2hpo","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/OCTRI/fhir2hpo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCTRI%2Ffhir2hpo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCTRI%2Ffhir2hpo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCTRI%2Ffhir2hpo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCTRI%2Ffhir2hpo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OCTRI","download_url":"https://codeload.github.com/OCTRI/fhir2hpo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OCTRI%2Ffhir2hpo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29548201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T14:33:00.708Z","status":"ssl_error","status_checked_at":"2026-02-17T14:32:58.657Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T03:13:07.880Z","updated_at":"2026-02-17T15:01:17.752Z","avatar_url":"https://github.com/OCTRI.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FHIR to HPO\n\nThis library converts FHIR Observations to Human Phenotype Ontology (HPO) Terms when LOINCs and interpretable values are present. It accepts R5 FHIR Resources formatted using the [HAPI-FHIR Java library](https://hapifhir.io/). HAPI-FHIR also provides a number of [converters](https://hapifhir.io/hapi-fhir/docs/model/converter.html) that can be used to communicate with previous FHIR versions, so you are not limited to using this library on an R5 server.\n\n# Setup\n\nCompiling this library requires installation of [Maven](http://maven.apache.org/install.html) and [Java 8](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).\n\nIn addition, you need to locally install the [monarch-initiative phenol library](https://github.com/monarch-initiative/phenol) that defines the domain around the HPO. This project is not yet available on Maven Central. From the command line:\n\n```\ngit clone https://github.com/monarch-initiative/phenol.git\ncd phenol\ngit checkout v.1.2.6\nmvn install\n``` \n\nThis checks out and builds Release 1.2.6 of phenol. \n\nOnce phenol is installed, install the fhir2hpo library. You can either clone this repo and build from master or check out a release tag. Run `mvn clean install` to build and deposit the new dependency into your maven repository.\n\n## Using the library\n\nfhir2hpo can be included in your maven project as a dependency:\n\n```\n\u003cdependency\u003e\n\t\u003cgroupId\u003eorg.monarchinitiative\u003c/groupId\u003e\n\t\u003cartifactId\u003efhir2hpo\u003c/artifactId\u003e\n\t\u003cversion\u003e1.0.5\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nTo perform conversion of a FHIR Observation to HPO Terms, use the ObservationAnalysisService provided by this library. In a Spring Boot application, you can autowire this service and access the associated domain by scanning the fhir2hpo packages.\n\n```\npackage org.myapp.pkg;\n\n@SpringBootApplication\n@EntityScan(basePackages = { \"org.myapp.pkg\", \"org.monarchinitiative.fhir2hpo\" })\n@ComponentScan({ \"org.myapp.pkg\", \"org.monarchinitiative.fhir2hpo\" })\npublic class MyApp {\n\n\t@Autowired\n\tObservationAnalysisService observationAnalysisService;\n\n\tpublic static void main(String[] args) {\n\t\tSpringApplication.run(MyApp.class, args);\n\t}\n}\n```\n\nThen pass observations to the service to convert:\n\n```\nObservation observation = getObservationFromFhirServer(...);\nObservationConversionResult observationConversionResult = observationAnalysisService.convert(observation);\n```\n\nTwo other services are provided that may be useful. The HpoService provides additional information about an HPO Term given a TermId. This is where you would find the term name (e.g., HP:0003573 =\u003e Increased total bilirubin).\n\nThe AnnotationService provides information about how LOINC Codes are mapped to HPO Terms.\n\n## Understanding the ObservationConversionResult\n\nIn most cases, an observation will contain a single LOINC along with a corresponding value. However, multiple LOINCs are possible, and for LOINC panels, the observation may contain several component LOINCs with individual values corresponding to each. The ObservationConversionResult encapsulates this by providing a list of LoincConversionResults, one for each LOINC in the observation. If the list is empty, then no LOINCs were found.\n\nThe conversion of a specific LOINC to an HpoTerm can fail for a variety of reasons. Conversion might also succeed using one method but fail using another. The entity LoincConversionResult encapsulates the full context of the attempted conversion so the consumer has detailed information and can decide how to handle the result. This includes information about success and failure along with a LoincObservationInfo object that breaks out information from the observation specific to the LOINC.\n\nConsider the example below:\n\n```\n{\n\t\"resourceType\": \"Observation\",\n\t...\n\t\"code\": {\n\t\t\"coding\": [{\n\t\t\t\"system\": \"http://loinc.org\",\n\t\t\t\"code\": \"55284-4\",\n\t\t\t\"display\": \"Blood pressure systolic and diastolic\",\n\t\t\t\"userSelected\": false\n\t\t}, {\n\t\t\t\"system\": \"http://loinc.org\",\n\t\t\t\"code\": \"8716-3\",\n\t\t\t\"display\": \"Vital Signs grouping\",\n\t\t\t\"userSelected\": false\n\t\t}],\n\t\t\"text\": \"BP\",\n\t\t\"component\": [{\n\t\t\t\t\"code\": {\n\t\t\t\t\t\"coding\": [{\n\t\t\t\t\t\t\"system\": \"http://loinc.org\",\n\t\t\t\t\t\t\"code\": \"8480-6\",\n\t\t\t\t\t\t\"display\": \"Systolic blood pressure\"\n\t\t\t\t\t}]\n\t\t\t\t},\n\t\t\t\t\"valueQuantity\": {\n\t\t\t\t\t\"value\": 107,\n\t\t\t\t\t\"unit\": \"mmHg\",\n\t\t\t\t\t\"system\": \"http://unitsofmeasure.org\",\n\t\t\t\t\t\"code\": \"mm[Hg]\"\n\t\t\t\t},\n\t\t\t\t\"interpretation\": {\n\t\t\t\t\t\"coding\": [{\n\t\t\t\t\t\t\"system\": \"http://hl7.org/fhir/v2/0078\",\n\t\t\t\t\t\t\"code\": \"N\",\n\t\t\t\t\t\t\"display\": \"normal\"\n\t\t\t\t\t}],\n\t\t\t\t\t\"text\": \"Normal\"\n\t\t\t\t}\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"code\": {\n\t\t\t\t\t\"coding\": [{\n\t\t\t\t\t\t\"system\": \"http://loinc.org\",\n\t\t\t\t\t\t\"code\": \"8462-4\",\n\t\t\t\t\t\t\"display\": \"Diastolic blood pressure\"\n\t\t\t\t\t}]\n\t\t\t\t},\n\t\t\t\t\"valueQuantity\": {\n\t\t\t\t\t\"value\": 60,\n\t\t\t\t\t\"unit\": \"mmHg\",\n\t\t\t\t\t\"system\": \"http://unitsofmeasure.org\",\n\t\t\t\t\t\"code\": \"mm[Hg]\"\n\t\t\t\t},\n\t\t\t\t\"interpretation\": {\n\t\t\t\t\t\"coding\": [{\n\t\t\t\t\t\t\"system\": \"http://hl7.org/fhir/v2/0078\",\n\t\t\t\t\t\t\"code\": \"L\",\n\t\t\t\t\t\t\"display\": \"low\"\n\t\t\t\t\t}],\n\t\t\t\t\t\"text\": \"Below low normal\"\n\t\t\t\t}\n\t\t\t}\n\t\t]\n\t}\n}\n```\n\nConverting this observation would return four LoincConversionResults, 2 from the code section and 2 from the components section. Each result contains getters for the relevant LoincId and LoincObservationInfo. The LoincObservationInfo for \"8462-4\" would contain the description of the test \"Diastolic Blood Pressure\" and the accompanying value and interpretation of \"60 mmHg\" and \"Low\". The LoincConversionResult also has methods for interrogating success or failure of the conversion as a whole or using specific methods (e.g., Interpretation).\n\nThe conversion as a whole may fail if LOINCs are not annotated by the library. Assuming conversion is possible, three different methods are attempted. These will proceed regardless of the success or failure of previous methods.\n\n1. Interpretation: Look for an interpretation code for the LOINC that can be mapped to an HPO Term.\n2. Value Quantity and Reference Range: Look for a reference range provided by the observation, and determine whether the value is low, high, or within range and map to an Hpo Term\n3. Value String: Look for a Value String that can be interpreted seeking common terms like \"positive\", \"negative\", etc.\n\nIt is possible, though rare, that the HpoTerm for one method will not match the term for another. In this case, all terms are returned in the result, and the consumer can decide how to handle.\n\n## Examples\n\nThere are two open-source projects using the library that can serve as examples.\n\nThis proof-of-concept [web application](https://github.com/OCTRI/poc-hpo-on-fhir) searches for users in a FHIR sandbox and converts their observations to HPO Terms. This application is capable of communicating with earlier versions of FHIR servers and provides examples of converting the responses to R5 so they can be used by the library.\n\nThis [statistics gatherer](https://github.com/OCTRI/f2hstats) collects observations from several sandboxes and stores the conversion results in a database where it is easy to qualify the types of observations encountered and the successes/failures of the library. Currently it can only communicate with a small set of unauthenticated sandboxes, but it can be easily adapted to capture real EHR data and even to obscure any PHI so that only aggregate information is recorded. This should work with release 1.0.3 of this library which expected STU3 observations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctri%2Ffhir2hpo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foctri%2Ffhir2hpo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctri%2Ffhir2hpo/lists"}