Gen-EpiX 7.1.0

Genomic Epidemiology platform for disease X

---

Gen-EpiX: Genomic Epidemiology platform for disease X (beta version)

Gen-EpiX is a platform for visualizing and analyzing genomic epidemiology data. It has fine-grained access controls for collaboration between multiple organizations.

The platform is currently at the beta release stage and as such not yet usable for production. We are currently working to get the platform released, for use in the Netherlands as the official national platform for laboratory-based surveillance of infectious diseases. Feel free to contact us here if you are interested.

This repository contains the code for the backend and is one of several that together comprise the platform. See https://github.com/RIVM-bioinformatics/gen-epix for an overview of the repositories.

Key Features

• Visualisation: Visualize cases by time, place, person and also by genome through a phylogenetic tree coupled to the cases.
• Fine-grained access: Give different organizations different access rights per disease, down to individual variables. Organizations can manage access of their own users by themselves.
• Search: Search and filter cases, including on genetic similarity.
• Signal detection: Detect, define and share sets of cases, signals and outbreaks. Detection can be manual through the web application, or through your own algorithm using the API.
• Disease X: Any disease and corresponding analysis variables can be added.
• Data: Adheres to the Medallion data architecture design pattern. The silver layer consists of normalized and standardized patient or subject data compliant with the OMOP Common Data Model, and a dedicated database for genetic sequence data and computation of phylogenetic trees. The gold layer consists of case data ready for analysis in the form of a single row of data per case.
• Tech: OpenAPI compliant API, deployable on cloud or on-premise, support for multiple authentication providers. Python/FastAPI backend and default TypeScript/React frontend available from gen-epix-web.

Deliberately not in scope

• Disease-specific knowledge: Every organization has their own variables that are important for analysis, as well as their own bioinformatics to process genetic sequence data. We therefore avoided any disease-specific code both for the generation of these data and for the analysis variables that can be defined. Only the results are stored.
• Collaboration-specific knowledge: Every collaboration or country (e.g. for public health surveillance of diseases) has their own specifics in terms of access rights and any relevant geographic regions. We therefore avoided any country-specific code, both for the type of organizations that have access, and for any geographic data.

---

Installation

1. Install ODBC development headers:

   # Linux
   sudo apt-get update
   sudo apt-get install -y unixodbc-dev
   

2. Create and activate a conda environment:

   conda create --name gen-epix python=3.13
   conda activate gen-epix
   

3. Install dependencies*:

   pip install -r requirements.txt
   pip install --no-binary :all: pyodbc==5.2.*
   

   Some hardware architectures (especially Apple M1/M2/M3 chips) require pyodbc to be compiled from source for compatibility*

4. For development, add testing tools:

   pip install -r dev-requirements.txt
   

SSL Certificate Setup

1. Install mkcert:

   # Linux
   sudo apt install mkcert
   
   # macOS
   brew install mkcert
   

2. Generate certificates:

   mkcert -install
   mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1
   

3. Copy the generated files:

   cp key.pem cert.pem /path/to/project/cert/
   

4. For WSL users: Run the commands in Windows PowerShell and copy files to both the project cert directory and your WSL home directory.

---

Usage

Starting the API

1. Activate the conda environment:

conda activate gen-epix

2. Run the application:

python run.py [service] [app_type] [env_name] [idp_config]

• service: The service to run (api, etl)
• app_type: Specific configuration for an app type (casedb, seqdb, omopbd)
• env_name: Name of the environment.
• idp_config: Which authentication setting to use (idps, mock_idps, debug)

---

Example

conda activate gen-epix
python run.py api casedb local idps

---

Dependencies

Gen-EpiX relies on several Python packages to provide its functionality:

Core Dependencies

• fastapi - Modern, high-performance web framework
• sqlalchemy - SQL toolkit and Object-Relational Mapping (ORM) library
• pydantic - Data validation and settings management
• biopython - Tools for computational molecular biology

Database Connectors

• pyodbc - ODBC database adapter

Development Tools

• pytest - Testing framework
• black - Code formatter
• pylint - Static code analyzer
• mypy - Static type checker

For a complete list of dependencies, refer to:

• requirements.txt - Production dependencies
• dev-requirements.txt - Development dependencies

Python Version Gen-EpiX requires Python 3.13 or higher.

Funding

This work was funded by the European Union under the EU4Health Programme (EU4H), project IDs 101102070 (UNITED4Surveillance) and 101113520 (NLWGSHERA2).

Disclaimer: Funded by the European Union. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or Health and Digital Executive Agency. Neither the European Union nor the granting authority can be held responsible for them.