fhir-moldef

Overview

Welcome to the fhir-moldef repository. This project provides a Python implementation of the HL7 (Health Level Seven) Fast Healthcare Interoperability Resources (FHIR) Molecular Definition standard. It enables users to create instances of the MolecularDefinition resource and currently supports three profiles: Sequence, Allele, and Variant.

Additionally, this repository supports seamless, bidirectional translation between Global Alliance for Genomics and Health (GA4GH) Variant Representation Specification (VRS) Alleles (v2.0) and the FHIR Allele Profile, enabling interoperability between the two standards.

Disclaimer

This project uses the MolecularDefinition schema from the latest in-progress development version: Work in Progress Schema. This page may occasionally be unavailable due to active development.

It does not match the schema in the HL7 FHIR 6.0.0 Ballot 2 release: FHIR Ballot 2 Schema.

Core Functionality

Category	Currently Supported
Resource	Generation of HL7 FHIR MolecularDefinition resources
Profiles	Sequence, Allele, and Variant profiles
Translation	Bidirectional translation between VRS 2.0 and FHIR (full + minimal)
Notebooks	Interactive Jupyter notebooks with examples (see the Notebooks README for details)
Pipeline	Extraction of VRS Allele objects from ClinVar variation files and translation into the FHIR Allele Profile

Installation Status

fhir-moldef is available on PyPI: https://pypi.org/project/fhir-moldef/

For users who want to work directly with the source code, local development setup instructions are also provided below.

Prerequisites

• Python 3.11–3.13
• Virtual environment (uv recommended): used to manage project dependencies

Dependencies & Infrastructure

The following infrastructure is required only for the VRS ↔ FHIR translation functionality:

• PostgreSQL 14
• SeqRepo (biocommons.seqrepo)

These dependencies are not required if you only plan to instantiate MolecularDefinition profiles.

For instructions on installing and configuring SeqRepo, see the VRS-Python SeqRepo installation guide.

Containerized setup instructions using Podman are planned, including configuration for running SeqRepo (and future UTA support).

Installation Steps

1. Install fhir-moldef with pip

fhir-moldef is available on PyPI.

pip install fhir-moldef

2. Optional: install additional dependencies

Additional dependency groups are available for translator functionality, example notebooks, and development tools. You can choose the dependency groups that best fit your use case.

To install all optional dependency groups:

pip install "fhir-moldef[translators,notebooks,dev]"

Local Development Setup

Clone the repository and create a local development environment if you want to work directly with the source code.

git clone https://github.com/InformaticsGenomicMedicine/fhir-moldef.git
cd fhir-moldef

uv venv
source .venv/bin/activate

# Optional extras: dev, notebooks, translators
# Install all extras with: uv sync --all-extras
# Install multiple extras with: uv sync --extra dev --extra notebooks
uv sync --extra dev

Contributing

Contributions are welcome! Please feel free to fork the repository and submit a pull request.
You can also report bugs or suggest improvements by opening an issue.

Acknowledgments

This project builds upon the following community standards and open-source implementations.

Standards

• GA4GH Variation Representation Specification (VRS)
• HL7 FHIR MolecularDefinition

Software

• vrs-python
• biocommons.seqrepo
• fhir.resources
• fhir-core

We gratefully acknowledge the communities and contributors who develop and maintain these standards and software projects.