A Nextflow pipeline for converting Mycobacterium tuberculosis Deeplex Myc-TB Excel genomic data to HL7 FHIR R4 Genomics format (IG v3.0.0). Full documentation

Installation

From the repo

git clone https://github.com/oucru-id/tb-to-fhir-deeplex.git
cd tb-to-fhir-deeplex

From the Docker

docker pull robind1/tb-to-fhir-deeplex:v1.4.1

Directory Structure

tb-to-fhir-deeplex
├── main.nf                          # Main workflow
├── nextflow.config                  # Configuration
├── workflows/
│   ├── deeplex.nf                   # Deeplex processing
│   ├── upload_fhir.nf               # FHIR uploader
│   └── utils.nf                     # Utility functions
├── scripts/
│   ├── xlsx_json_converter.py       # Deeplex to FHIR converter
│   ├── merge_clinical_deeplex.py    # DiagnosticReport data merge
│   └── get_versions.py              # Version collection
│   └── upload_fhir.py               # FHIR uploader
│   └── get_access_token.py          # Standalone script to get the access token to FHIR server
│   └── get_patient_by_nik.py        # Standalone script to get patient UUID
└── data/
│   ├── Deeplex/
│   └── access_token.json              # Access token generated
│   └── input_sso.json                 # SSO info to generate token
│   └── sampletopatientid_mapping.csv  # Mapping patient UUID with Deeplex's sample ID 

Input Data

Deeplex Files

Place Excel files in data/Deeplex/ directory

Setup

Create and activate a virtual environment before using the CLI scripts:

python3 -m venv venv
source venv/bin/activate

Usage

Get Access Token to FHIR Server

Fill the input_sso.json first

python3 scripts/get_access_token.py

Basic Run

nextflow run main.nf

Search for Patient UUID

Get the access token first

python scripts/get_patient_by_nik.py --nik 1234567890 --fhir_base_url "https://<BASE_URL>/fhir"

Run and Upload to FHIR Server

Get the access token and fill the patient UUID mapping first before running the pipeline

nextflow run main.nf \
  --fhir_server_url "https://<BASE_URL>/fhir"

Usage (Docker)

Get Access Token to FHIR Server

Fill the input_sso.json first

docker run --rm \
  -v /your/host/data:/pipeline/data \
  robind1/tb-to-fhir-deeplex:v1.4.1 \
  get-token --sso /pipeline/data/input_sso.json --out /pipeline/data/access_token.json

Basic Run

docker run --rm \
  -v /your/host/data:/pipeline/data \
  -v /your/host/results:/pipeline/results \
  robind1/tb-to-fhir-deeplex:v1.4.1 \
  run main.nf

Search for Patient UUID

Get the access token first

docker run --rm \
  -v /your/host/data:/pipeline/data \
  robind1/tb-to-fhir-deeplex:v1.4.1 \
  get-patient \
  --nik 1234567890 \
  --fhir_base_url "https://<BASE_URL>/fhir"

Run and Upload to FHIR Server

Get the access token and fill the patient UUID mapping first before running the pipeline

docker run --rm \
  -v /your/host/data:/pipeline/data \
  -v /your/host/results:/pipeline/results \
  robind1/tb-to-fhir-deeplex:v1.4.1 \
  run main.nf --fhir_server_url "https://<BASE_URL>/fhir"

Drug Resistance Classification

The DiagnosticReport conclusion is derived using the following order:

Classification	Criteria
XDR-TB	MDR/RR + Fluoroquinolone resistance + Group A drug resistance
Pre-XDR-TB	MDR/RR + Fluoroquinolone resistance
MDR-TB	Resistance to both Isoniazid and Rifampicin
RR-TB	Rifampicin resistance only
HR-TB	Isoniazid resistance only
Mono-resistant	Single drug resistance (Streptomycin, Ethionamide, Pyrazinamide, Ethambutol, or Ciprofloxacin)
Drug-resistant	Any other resistance combination
Sensitive	No resistance detected

Output Structure

results/
├── fhir_deeplex/                      # Deeplex-derived FHIR
│   └── deeplex_batch_001.json
├── fhir_deeplex_merged/               # Deeplex FHIR + DiagnosticReport
│   └── deeplex_batch_001.merged.fhir.json
├── fhir_upload/                       # Uploaded FHIR responses
│   └── deeplex_batch_001.merged.fhir.upload.json
└── runningstat/                       # Nextflow execution reports
    ├── execution.html
    ├── timeline.html
    └── dag.html

Support

GitHub Issues