rarelink 2.0.6

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

Framework

Packages & Compatibility

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

-> This way to the RareLink FHIR Implementation Guide

---

Table of Contents

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

Project Description

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, all RareLink-CDM pipelines are preconfigured to generate FHIR resources compliant with the HL7 International Patient Summary , HL7 Genomics Reporting profiles 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. RareLink-Phenopacket Engine: Predefined configurations enable seamless export of the RD-CDM data and extensions to validated Phenopackets -> User Guide.
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.0, the HL7 GenomicsReporting v3.0.0 and FHIR Base Resources (v4.0.1).
   • RareLink FHIR Implementation Guide in draft
6. Customising RareLink & 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 requires Python ≥3.10 and <3.13.

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

Core install

pip install rarelink

This installs everything needed for REDCap interaction, Phenopacket export, and the RareLink CLI. It does not install Docker, numpy/pandas, or documentation/testing tools.

Optional extras

Extra	Install command	What it adds
fhir	pip install rarelink[fhir]	Docker SDK for the toFHIR FHIR export pipeline
data	pip install rarelink[data]	numpy + pandas for tabular data processing
test	pip install rarelink[test]	pytest and pytest-mock
docs	pip install rarelink[docs]	Sphinx and documentation themes
dev	pip install rarelink[dev]	All of the above plus build/twine/jupyter

For development:

git clone https://github.com/BIH-CEI/rarelink.git
cd rarelink
pip install -e .[dev]
pytest

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 (this may take a while...):

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

Resources

Ontologies

• Human Phenotype Ontology (HP) 🔗
• Monarch Initiative Disease Ontology (MONDO) 🔗
• Online Mendelian Inheritance in Man (OMIM) 🔗
• Orphanet Rare Disease Ontology (ORDO) 🔗
• National Center for Biotechnology Information Taxonomy (NCBITaxon) 🔗
• Logical Observation Identifiers Names and Codes (LOINC) 🔗
• HUGO Gene Nomenclature Committee (HGNC) 🔗
• Gene Ontology (GO) 🔗
• NCI Thesaurus OBO Edition (NCIT) 🔗

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.

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:
  • Adam SL Graefe
  • Filip Rehburg
  • Samer Alkarkoukly
  • Daniel Danis
  • Peter N. Robinson
  • Sylvia Thun
  • Oya Beyan