194 release205

.gitignore

@@ -25,6 +25,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+RELEASE.md
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

MANIFEST.in

@@ -22,7 +22,7 @@ prune src/fsh/input-cache
 prune src/fsh/temp
 prune src/fsh/template
 
-# Common CI/dev folders you don't need in sdist (optional)
+# Common CI/dev folders you don't need in sdist
 prune .github
 prune .git
 prune .venv

README.md

@@ -1,18 +1,15 @@
 <p align="center">
-  <img src="docs/_static/res/rarelink_logo_no_background.png" alt="RareLink logo" width="400"/>
+  <img src="docs/_static/res/rarelink_logo_no_background.png" alt="RareLink logo" width="300"/>
 </p>
 
-A novel rare disease framework for REDCap linking international
-registries to FHIR and Phenopackets.
-
 #### Framework
 <!-- RareLink Badges -->
 [![Python CI](https://github.com/BIH-CEI/rarelink/actions/workflows/python_ci.yml/badge.svg)](https://github.com/BIH-CEI/rarelink/actions/workflows/python_ci.yml)
 [![Documentation Status](https://readthedocs.org/projects/rarelink/badge/?version=latest)](https://rarelink.readthedocs.io/en/latest/?badge=latest)
 ![Python Versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue) 
 [![PyPI](https://img.shields.io/pypi/v/rarelink.svg)](https://pypi.org/project/rarelink/)
 [![Downloads](https://img.shields.io/pypi/dm/rarelink.svg?label=downloads)](https://pypi.org/project/rarelink/)
-[![License: Apache v2.0](https://img.shields.io/badge/License-Apache2.0-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: Apache v2.0](https://img.shields.io/badge/License-Apache2.0-yellow.svg)](https://github.com/BIH-CEI/rarelink/blob/develop/LICENSE)
 [![DOI](https://zenodo.org/badge/832241577.svg)](https://doi.org/10.5281/zenodo.14253810)
 
 #### Packages & Compatibility
@@ -25,12 +22,15 @@ registries to FHIR and Phenopackets.
 [![FHIR IPS v2.0.0](https://img.shields.io/badge/FHIR_IPS-v2.0.0-purple)](https://build.fhir.org/ig/HL7/fhir-ips/)
 [![FHIR Genomics Reporting v3.0.0](https://img.shields.io/badge/FHIR_Genomics_Reporting-v3.0.0-yellow)](https://hl7.org/fhir/uv/genomics-reporting/STU3/general.html#findings)
 
+A novel REDCap-based framework for rare disease interoperability linking 
+international registries to HL7 FHIR and GA4GH Phenopackets. The corresponding
+paper was recently published in npj Genomic Medicine! 
+You can read it here: https://www.nature.com/articles/s41525-025-00534-z
 
 [-> This way to the RareLink documentation](https://rarelink.readthedocs.io/en/latest/) 
 
 [-> This way to the RareLink FHIR Implementation Guide](https://bih-cei.github.io/rarelink/) 
 
-> **Note:** The paper has been submitted to a journal - you can find the preprint here: https://www.medrxiv.org/content/10.1101/2025.05.09.25327342v1
 ________________________________________________________________________________
 
 ## Table of Contents
@@ -44,17 +44,19 @@ ________________________________________________________________________________
 - [Resources](#resources-)
 - [License](#license)
 - [Acknowledgements](#acknowledgements)
+- [Citing](#citing)
 
 ## Project Description
 
-RareLink - A novel rare disease framework in REDCap that connects international 
-registries, FHIR, and Phenopackets. It provides comprehensive 
+RareLink is a novel rare disease framework based on REDCap that connects 
+international registries, FHIR, and Phenopackets. It provides comprehensive 
 documentation and user guides to enable sustainable data management for your 
 local rare disease REDCap project.
 
 Built on the [RD-CDM](https://rarelink.readthedocs.io/en/latest/1_background/1_5_rd_cdm.html), 
 all RareLink-CDM pipelines are preconfigured to generate FHIR resources compliant
 with the [HL7 International Patient Summary](https://build.fhir.org/ig/HL7/fhir-ips/) 
+, [HL7 Genomics Reporting profiles](https://build.fhir.org/ig/HL7/genomics-reporting/) 
 or validated GA4GH Phenopackets. For disease-specific extensions, detailed guides  
 are available to help you develop sheets that integrate seamlessly with the 
 RareLink framework.
@@ -88,18 +90,16 @@ REDCap:
    data to the RareLink-CDM, which is in [LinkML](https://github.com/linkml/).
    This process includes syntactic mapping, local semantic encoding, validation,
    and data upload to REDCap for FHIR or Phenopacket export.
-4. **Phenopacket Export**: Predefined configurations enable seamless export of 
-   the RD-CDM data to validated Phenopackets utilising the [Phenopacket Mapper]((https://github.com/BIH-CEI/phenopacket_mapper)).
-   RareLink guides ensure compatibility for developing custom REDCap instruments
-   and [LinkML-based](https://github.com/linkml/) extensions.
+4. **RareLink-Phenopacket Engine**: Predefined configurations enable seamless 
+   export of the RD-CDM data and extensions to validated Phenopackets -> [User Guide](https://rarelink.readthedocs.io/en/latest/4_user_guide/4_3_phenopackets.html).
 5. **HL7 FHIR Export**: RareLink uses the open-source 
    [_toFHIR_ Engine](https://github.com/srdc/tofhir) to export data to any FHIR 
    server, supporting profiles based on the 
-   [HL7 International Patient Summary v2.0.2](https://build.fhir.org/ig/HL7/fhir-ips/),
+   [HL7 International Patient Summary v2.0.0](https://build.fhir.org/ig/HL7/fhir-ips/),
    the [HL7 GenomicsReporting v3.0.0](https://hl7.org/fhir/uv/genomics-reporting/STU3/index.html)
-   or FHIR Base Resources (v4.0.1).
-   - [FHIR Implementation Guide](https://bih-cei.github.io/rarelink/) 
-6. **RD-CDM Extensions**: [Guidelines for modeling and encoding custom data](https://rarelink.readthedocs.io/en/latest/4_user_guide/4_5_develop_redcap_instruments.html)
+   and FHIR Base Resources (v4.0.1).
+   - [RareLink FHIR Implementation Guide in draft](https://bih-cei.github.io/rarelink/) 
+6. **Customising RareLink & RD-CDM Extensions**: [Guidelines for modeling and encoding custom data](https://rarelink.readthedocs.io/en/latest/4_user_guide/4_5_develop_redcap_instruments.html)
    extensions ensure compatibility with the RareLink framework and its pipelines.
 
 ## Getting Started
@@ -163,7 +163,8 @@ BIOPORTAL_API_TOKEN=your_api_token_here
 
 ### Running Tests
 
-To ensure everything is set up correctly, run the test suite using `pytest`:
+To ensure everything is set up correctly, run the test suite using `pytest` (this
+may take a while...):
 
 ```bash
 pytest
@@ -240,7 +241,7 @@ the RareLink framework:
 
 Please write an issue or exchange with other users in the discussions if you
 encounter any problems or wish to give feedback. Feel free to reach out to 
-adam.graefe@charite.de, if you are interested in collaborating and improve the
+adam.graefe[at]charite.de, if you are interested in collaborating and improve the
 use of REDCap for rare disease research and care.
 
 ## Resources 
@@ -249,11 +250,11 @@ use of REDCap for rare disease research and care.
 - Human Phenotype Ontology (HP) [🔗](http://www.human-phenotype-ontology.org)
 - Monarch Initiative Disease Ontology (MONDO) [🔗](https://mondo.monarchinitiative.org/)
 - Online Mendelian Inheritance in Man (OMIM) [🔗](https://www.omim.org/)
-- Orphanet Rare Disease Ontology (OPRHA) [🔗](https://www.orpha.net/)
+- Orphanet Rare Disease Ontology (ORDO) [🔗](https://www.orpha.net/)
 - National Center for Biotechnology Information Taxonomy (NCBITaxon) [🔗](https://www.ncbi.nlm.nih.gov/taxonomy)
 - Logical Observation Identifiers Names and Codes (LOINC) [🔗](https://loinc.org/)
 - HUGO Gene Nomenclature Committee (HGNC) [🔗](https://www.genenames.org/)
-- Gene Ontology (GENO) [🔗](https://geneontology.org/)
+- Gene Ontology (GO) [🔗](https://geneontology.org/)
 - NCI Thesaurus OBO Edition (NCIT) [🔗](https://obofoundry.org/ontology/ncit.html)
 
 ### Submodules
@@ -268,6 +269,16 @@ This project is licensed under the terms of the [open-source Apache 2.0 License]
 We would like to extend our thanks to everyone in the last three years for their
  support in the development of this project.
 
+## Citing
+
+When using the software or its specifications please cite: 
+
+
+> Graefe, A.S.L., Rehburg, F., Alkarkoukly, S. et al. RareLink: scalable 
+  REDCap-based framework for rare disease interoperability linking 
+  international registries to FHIR and Phenopackets. 
+  npj Genom. Med. 10, 72 (2025). https://doi.org/10.1038/s41525-025-00534-z
+
 ---
 
 - Authors:

docs/12_contact.rst

@@ -8,6 +8,6 @@ Please check out our github Repository for more information:
 
 You can also email us directly at: 
 
-- `adam.graefe@charite.de`
+- adam.graefe[at]charite.de
 
 

docs/1_background/1_0_background_file.rst

@@ -3,6 +3,9 @@
 Background
 =============
 
+.. tip:: 
+   - **Manuscript:** RareLink was recently published in npj Genomic Medicine: https://www.nature.com/articles/s41525-025-00534-z
+
 RareLink was developed as a response to the widespread challenges in rare 
 disease (RD) data management, specifically the lack of interoperability and 
 standardization in healthcare information systems. As REDCap is widely used 

docs/1_background/1_2_ontologies.rst

@@ -94,8 +94,14 @@ The following codesystems are used in the RareLink Core Framework:
     The **Sequence Ontology** provides standardized vocabulary for genomic 
     annotation components, enhancing sharing and analysis of genomic information.
 
+:`MAXO <https://bioportal.bioontology.org/ontologies/MAXO>`_:
+    The **Medical Action Ontology (MAxO)** provides a structured vocabulary for 
+    medical procedures, interventions, therapies, and treatments for disease 
+    with an emphasis on rare disease (RD). MAxO provides a vocabulary to 
+    annotate diseases and phenotypes with recommended treatments and interventions.
+
 .. note:: The versions used by the RareLink Core Framework can be found here: 
-    `RareLink Ontologies <https://github.com/BIH-CEI/rarelink/blob/develop/src/rarelink_cdm/v2_0_2/datamodel/rarelink_code_systems.py>`_.
+    `RareLink Ontologies <https://github.com/BIH-CEI/rarelink/blob/develop/src/rarelink/rarelink_cdm/python_datamodel/rarelink_code_systems.py>`_.
 
 Further Reading
 ---------------

docs/1_background/1_5_rd_cdm.rst

@@ -4,12 +4,12 @@ RD-CDM
 =======
 
 .. tip::
-   The RD-CDM v2.0.2 has been published in Nature Scientific Data. You can read 
+   The RD-CDM has been published in Nature Scientific Data. You can read 
    it here: https://www.nature.com/articles/s41597-025-04558-z.
 
 _________________________________________________________________________________
 
-RD-CDM v2.0.2 Overview
+RD-CDM Overview
 -----------------------
 
 The ontology-based Rare Diseases Common Data Model (RD CDM) v2.0 was developed to address
@@ -24,9 +24,9 @@ involved overcoming challenges such as the lack of standardized terms for
 disease characteristics and the need to represent highly variable clinical data
 across different rare diseases.
 
-.. figure:: ../_static/res/rd_cdm_v2_0_2.svg
+.. figure:: ../_static/res/rd_cdm_v2_0_0.svg
 
-   Depicts version 2.0.2 of our ontology-based rare disease common data model (RD-CDM) based on the European Rare Disease Registry Infrastructure - Common Data Set (ERDRI-CDS), HL7 FHIR base resources v4.0.1 and the GA4GH Phenopacket Schema v2.0. The sections are derived from the ERDRI-CDS, and the section Diagnosis is extended by four subsections. For each section, all data elements and their data types. This data model does not define any cardinalities of relationships between elements or sections.
+   Depicts version 2.0.0 of our ontology-based rare disease common data model (RD-CDM) based on the European Rare Disease Registry Infrastructure - Common Data Set (ERDRI-CDS), HL7 FHIR base resources v4.0.1 and the GA4GH Phenopacket Schema v2.0. The sections are derived from the ERDRI-CDS, and the section Diagnosis is extended by four subsections. For each section, all data elements and their data types. This data model does not define any cardinalities of relationships between elements or sections.
 
 
 .. tip:: 
@@ -52,7 +52,7 @@ seamlessly integrated into existing healthcare systems without exceeding the
 avaliable resources is also essential. Addressing these complexities, the 
 RD CDM v2.0 provides a framework that enhances the consistency of rare disease 
 data, enabling better comparative analysis across research institutions and 
-healthcare settings. While the RD-CDM v2.0.2 is not a balloted version, it can 
+healthcare settings. While the RD-CDM v2.0.0 is not a balloted version, it can 
 serve as a template for future standardization efforts in rare disease research.
 
 Key success factors for the RD-CDM include its ability to support secondary

docs/2_rarelink_framework/2_0_rarelink_file.rst

@@ -3,6 +3,9 @@
 RareLink Framework
 ==================
 
+.. tip:: 
+   - **Manuscript:** RareLink was recently published in npj Genomic Medicine: https://www.nature.com/articles/s41525-025-00534-z
+
 In this section we elaborate on the development of the RareLink framework, how 
 it is designed to facilitate the management of rare disease data, and how it
 supports the creation of interoperable and reusable datasets. We provide an

docs/2_rarelink_framework/2_1_rarelink_overview.rst

@@ -3,6 +3,9 @@
 RareLink Overview
 =================
 
+.. tip:: 
+   - **Manuscript:** RareLink was recently published in npj Genomic Medicine: https://www.nature.com/articles/s41525-025-00534-z
+
 RareLink aims to maximise the utility of REDCap by providing a comprehensive 
 framework designed specifically for rare disease (RD) research and care. 
 At the core of RareLink is this documentation, the RareLink instruments that are 

docs/2_rarelink_framework/2_2_rarelink_cdm.rst

@@ -13,7 +13,8 @@ instrument, ensuring consistency and comprehensive data capture.
 
 .. hint:: 
     - Read the :ref:`1_6` page to understand how REDCap instruments & data dictionaries work.
-    - Read the :ref:`1_5` page for more information on the Rare Disease Common Data Model.
+    - Read the :ref:`1_5` page for more information on the ontology-based rare 
+      disease common data model.
 
 
 Contents
@@ -35,7 +36,7 @@ REDCap Data Dictionary
 
 The RareLink CDM Data Dictionary is available for download as a CSV file:
 
-:download:`Download: RareLink-CDM Data Dictionary (v2.0.2) <../../res/rarelink_cdm_datadictionary - v2_0_2.csv>`
+|data_dict_download|
 
 ... Next steps
 ________________
@@ -67,7 +68,7 @@ standards. In other words, the RareLink REDCap instruments are displayed in a
 structured format that so that LinkML modules and functionalities can be used.
 
 
-- Here you can view the `LinkML schema of the RareLink-CDM v2.0.2 <https://github.com/BIH-CEI/rarelink/tree/develop/src/rarelink_cdm/v2_0_2>`_. 
+- Here you can view the `LinkML schema of the RareLink-CDM <https://github.com/BIH-CEI/rarelink/tree/develop/src/rarelink/rarelink_cdm/schema_definitions>`_. 
 
 Usage 
 _______
@@ -79,7 +80,7 @@ modules, for example:
   from the REDCap project is automatically processed to the LinkML presentation
   of the RareLink-CDM and validated against it. This ensures the data is ready 
   to :ref:`4_3`. 
-- Within the data model itself, we use its `python classes and properties <https://github.com/BIH-CEI/rarelink/tree/develop/src/rarelink_cdm/v2_0_2/datamodel>`_ 
+- Within the data model itself, we use its `python classes and properties <https://github.com/BIH-CEI/rarelink/tree/develop/src/rarelink/rarelink_cdm/python_datamodel>`_ 
   automatically generated by LinkML schema to ensure consistent use of code 
   systems, versions and codes within one RareLink-CDM version and its mappings.
 - Since our RareLink-CDM is modeled and defined with LinkML, we can make use 
@@ -180,7 +181,7 @@ with REDCap's :ref:`rule_set`, the data dictionary requirements and to ensure
 alignment with:
 
 - international registries (e.g., the `European Reference Networks (ERNs) <https://health.ec.europa.eu/rare-diseases-and-european-reference-networks/european-reference-networks_en>`_),
-- the `HL7 FHIR International Patient Summary (IPS) v2.0.2 <https://build.fhir.org/ig/HL7/fhir-ips/>`_,
+- the `HL7 FHIR International Patient Summary (IPS) v2.0.0 <https://build.fhir.org/ig/HL7/fhir-ips/>`_,
 - the `HL7 Genomics Reporting v3.0.0 Profiles <https://hl7.org/fhir/uv/genomics-reporting/STU3/general.html>`_,  and
 - the `GA4GH Phenopacket Schema <https://rarelink.readthedocs.io/en/latest/1_background/1_3_ga4gh_phenopacket_schema.html>`_.
 

docs/2_rarelink_framework/2_3_rarelink_cli.rst

@@ -3,8 +3,6 @@
 RareLink CLI
 =============
 
-
-
 The RareLink Command Line Interface (CLI) is a tool that allows you to interact
 with the RareLink framework. The CLI provides a set of commands that allow you
 to set up and manage the RareLink framework, as well as to interact with the 

docs/3_installation/3_3_data_dictionary.rst

@@ -26,7 +26,7 @@ ________________________________________________________________________________
 
 1. **Download the instruments from the RareLink REDCap project.**
 
-- :download:`Download RareLink CDM Data Dictionary v2.0.2 <../../res/rarelink_cdm_datadictionary - v2_0_2.csv>`
+- |data_dict_download|
 
 2. **Upload the data dictionary to your REDCap project**
 

docs/4_user_guide/4_1_manual_data_capture.rst

@@ -431,8 +431,8 @@ ________________________________________________________________________________
 
 
 .. tip::
-  Define a set of rules for capturing measurements within a cohort to
-  improve subsequent analyses.
+  Define a set of rules for capturing measurements and procedures within 
+  a cohort to improve subsequent analyses.
 
 
 General Notes:
@@ -462,6 +462,35 @@ Fields:
   `OLS Platform <https://www.ebi.ac.uk/ols4/ontologies>`_ for
   ontology-specific searches if you cannot find the concepts you are looking for.
 
+The **Measurements** form can also be used to capture **medical procedures** by
+selecting the measurement category **``procedure``**.
+
+When the category **procedure** is selected:
+
+- The recorded information is interpreted as a **medical action**
+- The data are mapped differently depending on the target standard:
+
+**FHIR / IPS**
+  - The information is exported into the **FHIR-IPS Procedure Profile**
+  - Procedures **must** be encoded using **SNOMED CT**
+  - Whenever possible, use concepts from:
+    - `IPS Procedures Value Set <https://build.fhir.org/ig/HL7/fhir-ips/en/ValueSet-procedures-uv-ips.html>`_
+    - **SNOMED CT Body Structures** (for anatomical targets)
+
+**GA4GH Phenopackets**
+  - The information is stored in the **MedicalAction** block
+  - Procedures may be encoded using:
+    - **SNOMED CT**, or
+    - **MAXO (Medical Action Ontology)**
+  - While both are supported, **MAXO is recommended** where applicable,
+    as current and upcoming analysis algorithms developed by the **HPO team**
+    increasingly rely on MAXO-based representations.
+
+.. note::
+   Only **procedures** (not laboratory or quantitative measurements) should be
+   captured using the *procedure* category. All other observations should use
+   the appropriate measurement category (e.g. laboratory, vital signs).
+
 
 Return to `top <#top>`_.