<p align="center">
<img src="https://raw.githubusercontent.com/RIVM-bioinformatics/gen-epix-api/be6ec13a6f9d39be1e2a6dfbe6ba7b48ad2a2551/docs/assets/Gen-epix-logo.svg" alt="gen-epix-api-logo">
</p>
<p align="center">
<em>Genomic Epidemiology platform for disease X</em>
</p>
<p align="center">
<a href="https://github.com/RIVM-bioinformatics/gen-epix-api/actions/workflows/main.yml/badge.svg" target="_blank">
<img src="https://github.com/RIVM-bioinformatics/gen-epix-api/actions/workflows/main.yml/badge.svg" alt="tests">
</a>
<a href="https://sonarcloud.io/api/project_badges/measure?project=RIVM-bioinformatics_gen-epix-api&metric=alert_status&token=2b7eb8082cf1e05fb2fd03714413c6e5f8f4b74c" target="_blank">
<img src="https://sonarcloud.io/api/project_badges/measure?project=RIVM-bioinformatics_gen-epix-api&metric=alert_status&token=2b7eb8082cf1e05fb2fd03714413c6e5f8f4b74c" alt="sonarqube">
</a>
<a href="https://sonarcloud.io/api/project_badges/measure?project=RIVM-bioinformatics_gen-epix-api&metric=coverage&token=2b7eb8082cf1e05fb2fd03714413c6e5f8f4b74c" target="_blank">
<img src="https://sonarcloud.io/api/project_badges/measure?project=RIVM-bioinformatics_gen-epix-api&metric=coverage&token=2b7eb8082cf1e05fb2fd03714413c6e5f8f4b74c" alt="coverage">
</a>
</p>
---
**Source Code**: <a href="https://github.com/RIVM-bioinformatics/gen-epix-api" target="_blank">https://github.com/RIVM-bioinformatics/gen-epix-api</a>
---
# Gen-EpiX: Genomic Epidemiology platform for disease X (beta version)
Gen-EpiX is platform for visualizing and analyzing genomic epidemiology data. It has fine-grained access controls for collaboration between multiple organizations.
## 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.
- **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 <a href="https://www.ohdsi.org/data-standardization" target="_blank">OMOP Common Data Model</a>, 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:
```console
# Linux
sudo apt-get update
sudo apt-get install -y unixodbc-dev
```
2. Create and activate a conda environment:
```console
conda create --name gen-epix python=3.12
conda activate gen-epix
```
3. Install dependencies*:
```console
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*
<br>
4. For development, add testing tools:
```console
pip install -r dev-requirements.txt
```
**SSL Certificate Setup**
1. Install mkcert:
```console
# Linux
sudo apt install mkcert
# macOS
brew install mkcert
```
2. Generate certificates:
```console
mkcert -install
mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1
```
3. Copy the generated files:
```console
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:
```console
conda activate gen-epix
```
2. Run the application:
```console
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, no_auth, debug, no_ssl)
---
### Example
```console
conda activate gen-epix
python run.py api casedb local idps
```
<img src="https://github.com/RIVM-bioinformatics/gen-epix-api/blob/main/docs/assets/example_docs.png?raw=true" alt="example-docs">
---
## Dependencies
Gen-EpiX relies on several Python packages to provide its functionality:
**Core Dependencies**
* <a href="https://fastapi.tiangolo.com" target="_blank"><code>fastapi</code></a> - Modern, high-performance web framework
* <a href="https://www.sqlalchemy.org" target="_blank"><code>sqlalchemy</code></a> - SQL toolkit and Object-Relational Mapping (ORM) library
* <a href="https://docs.pydantic.dev" target="_blank"><code>pydantic</code></a> - Data validation and settings management
* <a href="https://biopython.org" target="_blank"><code>biopython</code></a> - Tools for computational molecular biology
**Database Connectors**
* <a href="https://github.com/mkleehammer/pyodbc" target="_blank"><code>pyodbc</code></a> - ODBC database adapter
**Development Tools**
* <a href="https://docs.pytest.org" target="_blank"><code>pytest</code></a> - Testing framework
* <a href="https://black.readthedocs.io" target="_blank"><code>black</code></a> - Code formatter
* <a href="https://pylint.org" target="_blank"><code>pylint</code></a> - Static code analyzer
* <a href="https://mypy.readthedocs.io" target="_blank"><code>mypy</code></a> - Static type checker
For a complete list of dependencies, refer to:
- [requirements.txt](requirements.txt) - Production dependencies
- [dev-requirements.txt](dev-requirements.txt) - Development dependencies
**Python Version**
Gen-EpiX requires Python 3.12 or higher.
Raw data
{
"_id": null,
"home_page": null,
"name": "Gen-EpiX",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "Genomic Epidemiology, Disease X, Bioinformatics",
"author": null,
"author_email": "RIVM-bioinformatics <ids-bioinformatics@rivm.nl>",
"download_url": "https://files.pythonhosted.org/packages/32/3a/593b98a9852bde915e272e9c35ca6d784bbcdfe1f06f88e2b2e3c3d10136/gen_epix-5.0.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/RIVM-bioinformatics/gen-epix-api/be6ec13a6f9d39be1e2a6dfbe6ba7b48ad2a2551/docs/assets/Gen-epix-logo.svg\" alt=\"gen-epix-api-logo\">\n</p>\n<p align=\"center\">\n <em>Genomic Epidemiology platform for disease X</em>\n</p>\n<p align=\"center\">\n <a href=\"https://github.com/RIVM-bioinformatics/gen-epix-api/actions/workflows/main.yml/badge.svg\" target=\"_blank\">\n <img src=\"https://github.com/RIVM-bioinformatics/gen-epix-api/actions/workflows/main.yml/badge.svg\" alt=\"tests\">\n </a>\n <a href=\"https://sonarcloud.io/api/project_badges/measure?project=RIVM-bioinformatics_gen-epix-api&metric=alert_status&token=2b7eb8082cf1e05fb2fd03714413c6e5f8f4b74c\" target=\"_blank\">\n <img src=\"https://sonarcloud.io/api/project_badges/measure?project=RIVM-bioinformatics_gen-epix-api&metric=alert_status&token=2b7eb8082cf1e05fb2fd03714413c6e5f8f4b74c\" alt=\"sonarqube\">\n </a>\n <a href=\"https://sonarcloud.io/api/project_badges/measure?project=RIVM-bioinformatics_gen-epix-api&metric=coverage&token=2b7eb8082cf1e05fb2fd03714413c6e5f8f4b74c\" target=\"_blank\">\n <img src=\"https://sonarcloud.io/api/project_badges/measure?project=RIVM-bioinformatics_gen-epix-api&metric=coverage&token=2b7eb8082cf1e05fb2fd03714413c6e5f8f4b74c\" alt=\"coverage\">\n </a>\n</p>\n\n\n\n---\n\n**Source Code**: <a href=\"https://github.com/RIVM-bioinformatics/gen-epix-api\" target=\"_blank\">https://github.com/RIVM-bioinformatics/gen-epix-api</a>\n\n---\n# Gen-EpiX: Genomic Epidemiology platform for disease X (beta version)\n\nGen-EpiX is platform for visualizing and analyzing genomic epidemiology data. It has fine-grained access controls for collaboration between multiple organizations.\n\n## Key Features\n\n- **Visualisation**: Visualize cases by time, place, person and also by genome through a phylogenetic tree coupled to the cases.\n- **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.\n- **Search**: Search and filter cases, including on genetic similarity.\n- **Signal detection**: Detect, define and share sets of cases, signals and outbreaks.\n- **Disease X**: Any disease and corresponding analysis variables can be added.\n- **Data**: Adheres to the Medallion data architecture design pattern. The silver layer consists of normalized and standardized patient or subject data compliant with <a href=\"https://www.ohdsi.org/data-standardization\" target=\"_blank\">OMOP Common Data Model</a>, 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.\n- **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.\n\n## Deliberately not in scope\n\n- **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. \n- **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. \n\n---\n\n# Installation \n\n1. Install ODBC development headers:\n ```console\n # Linux\n sudo apt-get update\n sudo apt-get install -y unixodbc-dev\n ```\n\n2. Create and activate a conda environment:\n ```console\n conda create --name gen-epix python=3.12\n conda activate gen-epix\n ```\n\n3. Install dependencies*:\n ```console\n pip install -r requirements.txt\n pip install --no-binary :all: pyodbc==5.2.*\n ```\n **Some hardware architectures (especially Apple M1/M2/M3 chips) require pyodbc to be compiled from source for compatibility*\n<br>\n\n4. For development, add testing tools:\n ```console\n pip install -r dev-requirements.txt\n ```\n\n\n**SSL Certificate Setup**\n\n1. Install mkcert:\n ```console\n # Linux\n sudo apt install mkcert\n \n # macOS\n brew install mkcert\n ```\n\n2. Generate certificates:\n ```console\n mkcert -install\n mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1\n ```\n\n3. Copy the generated files:\n ```console\n cp key.pem cert.pem /path/to/project/cert/\n ```\n\n4. For WSL users: Run the commands in Windows PowerShell and copy files to both the project cert directory and your WSL home directory.\n\n---\n\n## Usage\n\n### Starting the API\n\n1. Activate the conda environment:\n```console\nconda activate gen-epix\n```\n2. Run the application:\n```console\npython run.py [service] [app_type] [env_name] [idp_config]\n```\n- `service`: The service to run (api, etl) \n- `app_type`: Specific configuration for an app type (casedb, seqdb, omopbd)\n- `env_name`: Name of the environment.\n- `idp_config`: Which authentication setting to use (idps, mock_idps, no_auth, debug, no_ssl)\n\n---\n\n### Example\n\n```console\nconda activate gen-epix\npython run.py api casedb local idps\n```\n\n<img src=\"https://github.com/RIVM-bioinformatics/gen-epix-api/blob/main/docs/assets/example_docs.png?raw=true\" alt=\"example-docs\">\n\n---\n\n## Dependencies\n\nGen-EpiX relies on several Python packages to provide its functionality:\n\n**Core Dependencies**\n* <a href=\"https://fastapi.tiangolo.com\" target=\"_blank\"><code>fastapi</code></a> - Modern, high-performance web framework\n* <a href=\"https://www.sqlalchemy.org\" target=\"_blank\"><code>sqlalchemy</code></a> - SQL toolkit and Object-Relational Mapping (ORM) library\n* <a href=\"https://docs.pydantic.dev\" target=\"_blank\"><code>pydantic</code></a> - Data validation and settings management\n* <a href=\"https://biopython.org\" target=\"_blank\"><code>biopython</code></a> - Tools for computational molecular biology\n\n**Database Connectors**\n* <a href=\"https://github.com/mkleehammer/pyodbc\" target=\"_blank\"><code>pyodbc</code></a> - ODBC database adapter\n\n**Development Tools**\n* <a href=\"https://docs.pytest.org\" target=\"_blank\"><code>pytest</code></a> - Testing framework\n* <a href=\"https://black.readthedocs.io\" target=\"_blank\"><code>black</code></a> - Code formatter\n* <a href=\"https://pylint.org\" target=\"_blank\"><code>pylint</code></a> - Static code analyzer\n* <a href=\"https://mypy.readthedocs.io\" target=\"_blank\"><code>mypy</code></a> - Static type checker\n\nFor a complete list of dependencies, refer to:\n- [requirements.txt](requirements.txt) - Production dependencies\n- [dev-requirements.txt](dev-requirements.txt) - Development dependencies\n\n**Python Version**\nGen-EpiX requires Python 3.12 or higher.\n",
"bugtrack_url": null,
"license": null,
"summary": "Genomic Epidemiology platform for disease X",
"version": "5.0.0",
"project_urls": {
"Documentation": "https://rivm-bioinformatics.github.io/gen-epix-api/",
"Homepage": "https://github.com/RIVM-bioinformatics/gen-epix-api/"
},
"split_keywords": [
"genomic epidemiology",
" disease x",
" bioinformatics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "874bf0bb4e383dc736396e99536b1727e587a51d500dcc7fe56152c6d6c3fad2",
"md5": "31953c00f466eccd50f1224a96a33e58",
"sha256": "5f45e76fd19f34d1a76025632cb2c9afdc3a34c767c60a9a4fb0005b241134d7"
},
"downloads": -1,
"filename": "gen_epix-5.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "31953c00f466eccd50f1224a96a33e58",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 338695,
"upload_time": "2025-08-17T13:51:47",
"upload_time_iso_8601": "2025-08-17T13:51:47.769943Z",
"url": "https://files.pythonhosted.org/packages/87/4b/f0bb4e383dc736396e99536b1727e587a51d500dcc7fe56152c6d6c3fad2/gen_epix-5.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "323a593b98a9852bde915e272e9c35ca6d784bbcdfe1f06f88e2b2e3c3d10136",
"md5": "328d93dc0c89357a45f0a01193d45047",
"sha256": "f9821899b74b9969898db57fa70c6b8a788355579b13b12c8eb07ace4abbfa6a"
},
"downloads": -1,
"filename": "gen_epix-5.0.0.tar.gz",
"has_sig": false,
"md5_digest": "328d93dc0c89357a45f0a01193d45047",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 246684,
"upload_time": "2025-08-17T13:51:49",
"upload_time_iso_8601": "2025-08-17T13:51:49.822072Z",
"url": "https://files.pythonhosted.org/packages/32/3a/593b98a9852bde915e272e9c35ca6d784bbcdfe1f06f88e2b2e3c3d10136/gen_epix-5.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 13:51:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RIVM-bioinformatics",
"github_project": "gen-epix-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "fastapi",
"specs": [
[
"==",
"0.116.1"
]
]
},
{
"name": "uvicorn",
"specs": [
[
"==",
"0.32.1"
]
]
},
{
"name": "gunicorn",
"specs": [
[
"==",
"21.2.*"
]
]
},
{
"name": "starlette",
"specs": [
[
"==",
"0.41.3"
]
]
},
{
"name": "httpx",
"specs": [
[
"==",
"0.28.1"
]
]
},
{
"name": "python-jose",
"specs": [
[
"==",
"3.3.0"
]
]
},
{
"name": "sqlalchemy",
"specs": [
[
"==",
"2.0.43"
]
]
},
{
"name": "sqlalchemy_utils",
"specs": [
[
"==",
"0.41.2"
]
]
},
{
"name": "sqlmodel",
"specs": [
[
"==",
"0.0.24"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.7.*"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.2.3"
]
]
},
{
"name": "ulid-py",
"specs": [
[
"==",
"1.1.0"
]
]
},
{
"name": "fire",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "dynaconf",
"specs": [
[
"==",
"3.2.11"
]
]
},
{
"name": "types-setuptools",
"specs": [
[
"==",
"80.9.*"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.14.1"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.1.3"
]
]
},
{
"name": "biopython",
"specs": [
[
"==",
"1.85"
]
]
},
{
"name": "cachetools",
"specs": [
[
"==",
"5.5.2"
]
]
},
{
"name": "slowapi",
"specs": [
[
"==",
"0.1.9"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.*"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.4.*"
]
]
}
],
"lcname": "gen-epix"
}
JSON
