-
Notifications
You must be signed in to change notification settings - Fork 0
ORPHAcodes Technical Implementation
Nomenclature "pack" files via the ORPHAcodes website https://www.orphacode.org/pack-nomenclature/
give access to the ORPHAcodes nomenclature pack files.
Github is used to store current and previous version of ORPHAcodes nomenclature pack https://github.com/orphanet-rare-diseases-issues/RD-CODE and includes changelog between versions.
The API dedicated to ORPHAcodes nomenclature pack is accessible from https://api.orphacode.org and https://api.gouv.fr/les-api/api-orphacode (French governement official directory of APIs services). The ORPHAcodes API facilitates the informatic access to the Nomenclature Pack data and allows flexible implementation into the various IT systems in use in the different countries and/or settings. It also allows to build your datasets for specific national use cases. This API can allow to generate a sub-list of ORPHAcodes that may of interest at national level, for example only cardiac diseases or Excluding cancer and/or infectious diseases and/or intoxications => the API will provide the full list of ORPHAcodes for that particular use case. This adds however a layer of vigilance in terms of update at the local level as restricting the list of codes, makes the removed diseases not visible. The ORPHAcodes API can also be exploited for checking the validity of your code (i.e. Status: active/inactive): You can track the inactive codes, and also ask to retrieve, for deprecated entities, what is the new target code. See the technical description of this API below.
Other datasets available from Orphadata.com ARE NOT part of the ORPHAcodes nomenclature pack annual release. Orphanet provides also the Orphanet Rare Diseases Ontology (ORDO), which is not the ORPHAcodes nomenclature pack and is used for different purposes based on semantic technologies. See "what-is-the-difference-between-the-orphanet-nomenclature-files-and-ordo"
The Orphanet nomenclature files for coding are delivered on an annual basis, in July (see here). The previous versions stay available on the RD-CODE GitHub project as well as the change logs. Using Github functionalities, a technical user will have a full access to every “commit”, previous versions and changes. However, a “diff” excel file is provided with each release in the Nomenclature Pack files
https://www.orphacode.org/pack-nomenclature/
The Orphanet nomenclature pack compiles various files (listed below) which provide the computable information necessary to achieve implementation of ORPHAcodes in health information systems, and ensure easier and accurate coding. These files are updated once a year, in 9 different languages: Czech, Dutch, English, French, German, Italian, Polish, Portuguese and Spanish. Excel and PDF files are available in English and are common to all Orphanet nomenclature pack.
The main format is XML (Extensible Markup Language) as a text document, which could be parsed or used with Xpath queries.
Each year the Orphanet nomenclature pack includes :
- Orphanet nomenclature file (XML Schema Definitions and JPEG representations for this file).
- Orphanet to ICD-10 (XML Schema Definitions and JPEGrepresentations for this files) and ICD-11 mapping files (XML Schema Definitions and JPEG).
- Orphanet classifications files by medical specialities (XML Schema Definitions and JPEGrepresentations for these files).
- Linearisation file attributing one preferential medical specialty to every clinical entity (XML Schema Definitions and JPEG representations for this file).
- Master file (Excel file), contains the minimal set of ORPHAcodes at the disorder level, which is the aggregation level for statistical purposes), aligned with ICD-10 codes and ICD-11 codes, that should be used for data aggregation and statistical reporting at EU-level. The Master file is not natively intended for implementation purposes, as it lacks the granularity of the nomenclature. More information about the Master file can be found here.
- Orphanet nomenclature differential file (Excel file) which provides the key changes made to the nomenclature compared to the previous version.
- Description file (PDF file describing the xml files enclosed in the Orphanet nomenclature pack for coding).
The ORPHAcodes API is available through https://api.orphacode.org/
It's compliant with OpenAPI standard 3.0 https://api.orphacode.org/openapi.json. The API is fully documented. Every available "get" are described with expected parameters and results examples with Response Body and Response Header
The main format returned by the API calls will be JSON.
As the API is based on the yearly Orphanet Nomenclature Pack Content, it is updated every year in July and there is no intermediate updates between version. Therefore, you don't need to check for changes until the next releases.
Some JSON responses will contain a "Date" field
{ "ORPHAcode": 558, "Definition": "Marfan syndrome is a systemic disease of connective tissue characterized by a variable combination of cardiovascular, musculo-skeletal, ophthalmic and pulmonary manifestations.", "Date": "2024-06-27 12:14:14" }
Please note : This Date file indicate when the export of the content has been made from the Orphanet Knowledge base to generate the Orphanet Nomenclature Pack. It's not the creation nor update date of particular concept or entity.
Even if an API key is needed to test and use the API, for now it's not necessary to subscribe to the API. Any "token key" could be used. For instance (using CURL): curl -X GET "https://api.orphacode.org/EN/ClinicalEntity/orphacode/558/Definition" -H "accept: application/json" -H "apiKey: token"
The API ORPHAcodes front is hosted by a third party "GANDI" french based company. (Terms of use). As the ORPHAcodes Nomenclature Pack is free of sensitive or personal data (no patients data), GDPR or Health data hosting constrains does not apply. the API ORPHAcodes use an ElasticSearch cloud instance to serve queries and results.
The ORPHAcodes API is freely accessible, and no subscription is needed for now. Therefore there is no "contract" or SLA (Service Level Agreement) available or possible. We cannot guarantee access 24/7 or constant performances on queries. (Even if the uptime is above 99% since 2022)
We have chosen to apply the Commons Attribution 4.0 International (CC BY 4.0) to all copyrightable parts of our databases. This means that you are free to copy, distribute, display and make commercial use of these databases in all legislations, provided you give us credit.
You are free to implement the API within your own solutions/software/apps, but considering the Availability chapter above, using directly the API in a front-end production environment could be not fully recommended. Especially to avoid critical dependicies. Consider also the yearly update of the content. Depending on your use case, it may not be relevant to repeat queries along the year until the next content release. Therefore, in most cases, the API is used to build your own backend for your software/app implementation. Some users have also done a mix between the XML files (to ingest large part of the dataset) and API to build their system.
The Orphanet Rare Disease ontology (ORDO) was initially jointly developed by Orphanet and the EBI to provide a structured vocabulary for rare diseases capturing relationships between diseases, genes and other relevant features which will form a useful resource for the computational analysis of rare diseases. The ontology is also produced according to the same pipeline as of the Nomenclature Pack: it is an export of the knowledge base of the disease content in a format that is semantically valid (links between different semantically defined concepts). However, ORDO is updated twice a year, in January and in July: only the July version corresponds to the reference Nomenclature for coding to be implemented in hospitals. ORDO/RDF is more expressive, but the the ORPHAcodes content is exactly the same only in the July release and more updated in the following January release. N.B. The canonical reference for coding is in the Nomenclature Pack, If you decide to use ORDO for implementation of ORPHAcodes in the HIS it is possible even if it is not the recommended way. If this is the case the July issue of ORDO should be used as this will have the same disease content of the Annual release of the Nomenclature Pack and this will allow comparability.
To avoid any discrepancies, for patients coding purposes, the usage of the Nomenclature Pack is recommended (“XML files”), nevertheless it is possible to use the ORPHAcodes API. Indeed, the content between “xml” files or ORPHAcodes API (json based) is fully consistent so you can choose the content that suits your system and needs the more. If you need to use “semantic technologies” (ontologies and reasoning, sparql, RDF/OWL etc.) you can use ORDO (with some attention with using the JULY release version of ORDO so that the content is equivalent with the July Nomenclature Pack release). If you need to expand your datasets and include HPO annotations, genes etc.: you can consider to use Orphadata knowledge files for that. Here again, the Orphanet Knowledge base (OrphadataScience), is updated twice a year, in January and in July, therefore we recommend to use the July release files.
What the different ORPHAcodes distribution media available contain (Nomenclature Pack vs API vs ORDO)? How do they differ?
As suggested a more visual representation of the content of each tool is provided in the table below.
XML is usually a format used to be parsed with languages such "python", "java" etc. Somehow, for non technical people, this could be easily converted into csv/excel files.
Warning this "tips" could may not work on your computer, depending of your own configuration. More over, this "automated" conversion could lead to misinterpretation of some datasets.
Pre-requisite: having Excel (above 2003 version) on a windows OS computer (seems not working properly on other platforms)
Once a XML files downloaded or unzipped on your computer, you can open it with Microsoft Excel. The software will attempt to interprete the content and generate a "flat" version of it. Once the conversion done, you can save the file into csv or excel format. Please not that Excel will generate several columns, trying to deal with the XML structure and therefore Excel will generate automatically names for those columns. Some of the columns names will be based on the XML tag, some of the names won't.
- The ORPHAcodes API can also be exploited for checking the validity of your code (i.e. Status: active/inactive) : You can track the inactive codes, and also ask to retrieve for the deprecated entities what is the new target code.
- “Differentials” file within the Nomenclature can be also checked and a technical user can also track changes within files content using GitHub (https://github.com/orphanet-rare-diseases-issues/RD-CODE )