-
Notifications
You must be signed in to change notification settings - Fork 0
Technical Implementation
Orphadata.com https://www.orphadata.com give access to the ORPHAcodes nomenclature pack files. Go to https://www.orphadata.com/pack-nomenclature/ page
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) See the technical description of this API below.
Services build around the ORPHAcodes nomenclature pack API and dataset are accessible from : https://www.orphadata.com/orphanet-nomenclature-for-coding/
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. The previous versions stay available on the RD-CODE GitHub project as well as the change logs. the API api.orphacodes.org and derived tools are all based on the Orphanet Nomenclature content and therefore are updated on same annual basis.
(https://www.orphadata.com/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 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 JPEG representations for this files) and ICD-11 mapping files ( XML Schema Definitions and JPEG).
- Orphanet classifications files by medical specialities ( XML Schema Definitions and JPEG representations 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), the minimal set of ORPHAcodes, aligned with ICD-10 codes, that should be used for data sharing and statistical purposes at EU-level. 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 Orphacode API will return results in JSON format.
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, 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.
"Dataviz" (see description) is a tool build with the API Orphacodes. It illustrates a way to implement the API in order to exploit the ORPHAcodes nomenclature pack and visualise the data in several ways. As the content is based on the ORPHAcodes nomenclature pack and the API, it's updated each year also. It includes search features, classifications features, export features. https://dataviz.orphacode.org/
As mentionned, the "Nomenclature Pack" content is updated on yearly basis (july). Therefore the dedicated API, Tools based on the API, Github repo are updated on the same yearly basis. There is no intermediate update, neither regarding the content or the format between annual release. Once the pack is released, no needs to check for changes until next release.
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...