rarelink 2.0.3

RareLink - A REDCap-based Python framework linking international registries to HL7 FHIR and GA4GH Phenopackets

A novel rare disease framework for REDCap linking international registries to FHIR and Phenopackets.

Framework

Packages & Compatibility

-> This way to the RareLink documentation

-> This way to the RareLink FHIR Implementation Guide

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

• Project Description
• Features
• Getting Started
  • Prerequisites
  • Installation
• Contributing
• Resources
• License
• Acknowledgements

Project Description

RareLink - A novel rare disease framework in 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, all RareLink-CDM pipelines are preconfigured to generate FHIR resources compliant with the HL7 International Patient Summary or validated GA4GH Phenopackets. For disease-specific extensions, detailed guides
are available to help you develop sheets that integrate seamlessly with the RareLink framework.

If you are familiar with REDCap but lack coding experience, you can still set up your local RareLink REDCap project and begin capturing data. However, some coding experience is recommended for accessing advanced functionalities.

Features

REDCap is a widely-used clinical electronic data capture system, licensed by institutions worldwide. RareLink enhances REDCap by providing detailed guidelines for structuring and encoding data to ensure seamless integration with its preconfigured FHIR and Phenopacket pipelines. Built on the Rare Disease Common Data Model v2.0 (RD-CDM) RareLink is ready-to-use and extensible for disease-specific requirements.

RareLink integrates the following features for rare disease data management in REDCap:

1. RareLink CLI: Set up and manage your project via the Command Line Interface, including API setup, instrument configuration, and running FHIR or Phenopacket pipelines.
2. Native REDCap Usage: Downloadable REDCap forms for all RD-CDM sections, complete with installation guides and manuals for manual data capture and BioPortal connection.
3. Semi-Automated Data Capture: Use a template script to map your tabular data to the RareLink-CDM, which is in 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. RareLink guides ensure compatibility for developing custom REDCap instruments and LinkML-based extensions.
5. HL7 FHIR Export: RareLink uses the open-source toFHIR Engine to export data to any FHIR server, supporting profiles based on the HL7 International Patient Summary v2.0.2, the HL7 GenomicsReporting v3.0.0 or FHIR Base Resources (v4.0.1).
   • FHIR Implementation Guide
6. RD-CDM Extensions: Guidelines for modeling and encoding custom data extensions ensure compatibility with the RareLink framework and its pipelines.

Getting Started

Begin by exploring the RareLink Background section to understand the framework's scope and components.

To start using RareLink, ensure you have access to a local REDCap license and a running REDCap server. For more information, visit the official REDCap site: https://projectredcap.org/partners/join/. If your institution already provides a REDCap instance, proceed to the RareLink Documentation on Setting Up a REDCap Project.

Installation

RareLink can be set up using various Python project management approaches. One common method is to use a virtual environment. Below is an example where the virtual environment is named rarelink-venv, but you can name it as you prefer:

python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

Note: You need Python ≥3.10 but <3.13 to be able to use RareLink!

Next, clone the RareLink repository, navigate to its root directory, and install RareLink using:

git clone https://github.com/BIH-CEI/rarelink.git
cd rarelink
pip install .

If you want to install development dependencies (e.g., pytest), use:

pip install .[dev]

Setting Up the .env File

Create a .env file in the project root directory to store your BioPortal API token securely. Add the following line:

BIOPORTAL_API_TOKEN=your_api_token_here

You can create your free BioPortal account here: https://bioportal.bioontology.org/ Then replace your_api_token_here with your actual BioPortal API token.

Running Tests

To ensure everything is set up correctly, run the test suite using pytest:

pytest

---

Notes

• Ensure that your .env file is not committed to version control by adding it to .gitignore.
• If you encounter issues, verify you are using the correct Python version and have installed all dependencies properly.

Framework setup

To ensure you have the latest version of RareLink installed and to check the current version, run:

rarelink framework update
rarelink framework status

REDCap setup

To set up your local REDCap project, run:

rarelink setup redcap-project

For additional setup guidance, use:

rarelink setup --help

This will provide details about available commands, such as:

• rarelink setup keys for configuring, viewing, or reseting your local API config file.
• rarelink setup download-records --help for downloading RareLink REDCap sheets.
• rarelink setup data-dictionary to upload the RareLink-CDM sheets to your REDCap project.

Note: Ensure that your local REDCap administrator has granted you API access to your REDCap project. Remember that the API token is sensitive information, so store it securely!

Semi-Automated Import to REDCap

To process and import your local (tabular) rare disease datasets into your RareLink REDCap project, refer to the user guide on Semi-Automatic Data Capture.

Export REDCap Data to FHIR

To export IPS-based FHIR resources to your local FHIR server, refer to the user guide on the IPS RareLink FHIR Export.

Export REDCap Data to Phenopackets

To export your REDCap RareLink data to validated Phenopackets, refer to the user guide on the RareLink Phenopacket Export.

Extensional Data Modeling in REDCap

To develop your local REDCap database for disease-specific extensions around the RD-CDM, refer to the guide on how to develop and model REDCap sheets for processing by the RareLink framework: RD-CDM RareLink Extension Guide.

Contributing

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 [e-mail], if you are interested in collaborating and improve the use of REDCap for rare disease research and care.

Resources

Ontologies

• Human Phenotype Ontology (HP, Version 2025-05-06) 🔗
• Monarch Initiative Disease Ontology (MONDO, Version Version 2025-06-03) 🔗
• Online Mendelian Inheritance in Man (OMIM, Version OMIM2024_08_09) 🔗
• Orphanet Rare Disease Ontology (OPRHA, Version OMIM2024_08_09) 🔗
• National Center for Biotechnology Information Taxonomy (NCBITaxon, Version 2024-07-03) 🔗
• Logical Observation Identifiers Names and Codes (LOINC, Version LNC278) 🔗
• HUGO Gene Nomenclature Committee (HGNC, Version 2024-08-23) 🔗
• Gene Ontology (GENO, Version 2023-10-08) 🔗
• NCI Thesaurus OBO Edition (NCIT, Version Version 24.01e ) 🔗

Submodules

• toFHIR

License

This project is licensed under the terms of the open-source Apache 2.0 License

Acknowledgements

We would like to extend our thanks to everyone in the last three years for their support in the development of this project.

---

• Authors:
  • Adam SL Graefe
  • Filip Rehburg
  • Samer Alkarkoukly
  • Daniel R Korn
  • Daniel Danis
  • Peter N. Robinson
  • Sylvia Thun
  • Oya Beyan