ZaroPGx — A Pharmacogenomic Analysis Platform

See the analysis in action: click below to watch a demo on YouTube:

---

What ZaroPGx Does

ZaroPGx is a self-hosted pharmacogenomic analytic pipeline. As input, ZaroPGx accepts a VCF, BCF, gVCF, BAM, CRAM, SAM or short-read FASTQ, and reports diplotypes and phenotypes for up to 91 pharmacogenes, with the CPIC, DPWG and FDA guidances that apply, with reports in PDF, interactive HTML, and FHIR R4 bundle forms.

• PharmCAT (25): ABCG2, CACNA1S, CFTR, CYP2B6, CYP2C9, CYP2C19, CYP2D6 (from PyPGx), CYP3A4, CYP3A5, CYP4F2, DPYD, F2, F5, G6PD, HLA-A and HLA-B (from OptiType), IFNL3, MT-RNR1 (from mtDNA-Server 2), NAT2, NUDT15, RYR1, SLCO1B1, TPMT, UGT1A1, VKORC1
• PyPGx (65): ABCB1, ACYP2, ADRA2A, ADRB2, ANKK1, APOE, ATM, BCHE, BDNF, COMT, CYP1A1, CYP1A2, CYP1B1, CYP2A6, CYP2A13, CYP2C8, CYP2E1, CYP2F1, CYP2J2, CYP2R1, CYP2S1, CYP2W1, CYP3A7, CYP3A43, CYP4A11, CYP4A22, CYP4B1, CYP17A1, CYP19A1, CYP26A1, DBH, DRD2, GRIK1, GRIK4, GRIN2B, GSTM1, GSTP1, GSTT1, HTR1A, HTR2A, IFNL4, ITGB3, ITPA, MTHFR, NAT1, OPRK1, OPRM1, POR, PTGIS, RARG, SLC6A4, SLC15A2, SLC22A2, SLC28A3, SLC47A2, SLCO1B3, SLCO2B1, SULT1A1, TBXAS1, UGT1A4, UGT1A6, UGT2B7, UGT2B15, UGT2B17, XPC
• OptiType (1): HLA-C

Workflow: Genomic data sample submission → Preprocessing (if needed) → OptiType HLA Allele Calling → mtDNA-Server 2 Mitochondrial DNA Allele Calling → PyPGx Allele Calling → Unlisted Variant Screening → PharmCAT phenotype matching with Outside Calls → Report Creation → optional FHIR export

Designed as a self-hostable Docker Compose stack, ZaroPGx enables absolute data privacy and security when loaded in a local and secure network. Reports are for informational purposes only and are not intended for use as a substitute for professional medical advice, diagnosis, or treatment.

Quickstart with One-Command Setup

PowerShell (Windows):

iwr -useb https://raw.githubusercontent.com/Zaromics/ZaroPGx/main/bootstrap.ps1 | iex

Bash (Linux / macOS / WSL):

curl -fsSL https://raw.githubusercontent.com/Zaromics/ZaroPGx/main/bootstrap.sh | bash

This single command will:

• Check for required dependencies (Git, Docker, Docker Compose)
• Offer to automatically install missing dependencies (with your permission)
• Download the ZaroPGx bootstrap script
• Clone the repository
• Create necessary directories
• Start the Docker compose containers

Security Note: If you're cautious about running remote scripts (which is good practice), you can inspect the bootstrap scripts here:

• PowerShell: https://raw.githubusercontent.com/Zaromics/ZaroPGx/main/bootstrap.ps1
• Bash: https://raw.githubusercontent.com/Zaromics/ZaroPGx/main/bootstrap.sh

To update an existing installation:

PowerShell:

iex "& { $(iwr -useb https://raw.githubusercontent.com/Zaromics/ZaroPGx/main/bootstrap.ps1) } -Update"

Bash:

curl -fsSL https://raw.githubusercontent.com/Zaromics/ZaroPGx/main/bootstrap.sh | bash -s -- --update

Status

This project is in early development.

Core functionality is being implemented incrementally:

Input formats

• Priority 0 (Supported): VCF, GRCh38/hg38, NGS-derived.
• Priority 1 (Supported): VCF, GRCh37/hg19, NGS-derived. Lifted over to GRCh38.
• [...] Priority 2 (Testing): BAM, CRAM, SAM, BCF, gVCF, NGS-derived, GRCh38.
• [...] Priority 2 (Testing): FASTQ, short reads, up to 20 GB. Aligned to GRCh38.
• [...] Priority 3 (Research): Other sequencing and genotyping formats.
• [...] Priority 4 (Research): BED, 23andMe, AncestryDNA, various TXT formats. Detected and refused for now.
• [...] Priority 5 (Early research): T2T-CHM13, and others. Detected and refused for now.

Features

• Priority 0 (Supported): PDF and interactive HTML custom in-house reports.
• Priority 1 (Supported): mtDNA-Server 2: haplogroup and the MT-RNR1 outside call.
• Priority 2 (Supported): FHIR R4 export (JSON, XML) following HL7's Genomics Reporting IG; push to the bundled HAPI FHIR server.
• [...] Priority 3 (Development): Interactive HTML enhancements with useful visualizations, fully DB-oriented data handling. Projected release in v0.5
• [...] Priority 4 (Research): FHIR online export direct to PHR/EHR
• [...] Priority 5 (Early research): In-depth and targeted analytics, with specialty curation to reduce cognitive load
• [...] Priority 6 (Early research): Complete transition to fully DB-based workflow; pulling and normalizing data directly from published databases

Requirements

Software

NB: The simple bootstrap script will automatically install missing dependencies for you!

Linux environment preferred

• Docker; Docker Compose (>= 2.24); Git -- at minimum
• Auto-install supported via: apt, yum, dnf, pacman

Windows 10/11 requires WSL2 installed and configured

• WSL2; Docker; Docker Compose; Git
• Auto-install supported via: winget or chocolatey

macOS requires either Docker Desktop or to run a Linux VM

• Auto-install supported via: homebrew (Git only; Docker Desktop must be installed manually)
• (macOS support needs testing)

Hardware

• Virtualization: Hardware Virtualization must be enabled for Windows and macOS users
• CPU: x86-64 (64-bit Intel or AMD)

(resource usage, projected)

• Internet connection: first run only requires significant bandwidth to fetch images and load reference genomes; advisable to NOT be on a metered connection, and preferably use a wired one.
• Hardware, Minimum (limited function): 4 CPU cores, 16 GB RAM, 100 GB storage
• Hardware, Acceptable (full function): 8 CPU cores, 32-64 GB RAM, 1 TB NVMe SSD storage
• Hardware, Preferred (fast, full function): 16 CPU cores, 128 GB ECC RAM, 2 TB NVMe SSD storage

Manual Installation (Advanced)

If you prefer more control or want to customize the installation:

1. Clone the repository

   git clone https://github.com/Zaromics/ZaroPGx.git
   cd ZaroPGx
   

2. Start services (the script asks which .env template to use)

   • PowerShell (Windows): .\start-docker.ps1
   • Bash (Linux / Mac / Windows WSL): ./start-docker.sh

3. Access the Main App

   • Web UI: http://localhost:8765
   • Documentation: http://localhost:8765/docs
   • HAPI FHIR dashboard (optional): http://localhost:8090

Usage

Web Interface (Recommended)

1. Open http://localhost:8765
2. Upload a genomic data file
3. Observe progress, and on completion you will see links to the custom PDF and interactive HTML reports, as well as PharmCAT's report and raw data outputs.

Reports are written to data/reports/<patient_id>/<job_id>/.

REST API (Advanced and Debugging)

See the FastAPI docs on your instance's page: http://localhost:8765/api/docs

Sample Data Access

For real-world sample data, try browsing the Personal Genome Project:

• https://www.personalgenomes.org/

Sample files available in the repo:

• app/static/demo/NA12878.pgx-demo.cram
• test_data/sample_cpic.vcf

Contributions are welcome and are gratefully appreciated!

Acknowledgements & Citations

If your work is a part of ZaroPGx and you wish to add or amend text recognizing yourself, your work, and/or your organization, please send me a message and I will gladly attend to your request.

Software

• Nextflow
  • Di Tommaso P, Chatzou M, Floden EW, Barja PP, Palumbo E, Notredame C. Nextflow enables reproducible computational workflows. Nature Biotechnology. 2017;35(4):316–319. doi:10.1038/nbt.3820
• SAMtools, BCFtools and HTSlib
  • Danecek P, Bonfield JK, Liddle J, et al. Twelve years of SAMtools and BCFtools. GigaScience. 2021;10(2):giab008. doi:10.1093/gigascience/giab008
  • Bonfield JK, Marshall J, Danecek P, et al. HTSlib: C library for reading/writing high-throughput sequencing data. GigaScience. 2021;10(2):giab007. doi:10.1093/gigascience/giab007
  • Danecek P, McCarthy SA. BCFtools/csq: haplotype-aware variant consequences. Bioinformatics. 2017;33(13):2037–2039. doi:10.1093/bioinformatics/btx100
• pysam
• GATK
  • Van der Auwera GA, O'Connor BD. Genomics in the Cloud: Using Docker, GATK, and WDL in Terra. 1st ed. O'Reilly Media; 2020.
  • McKenna A, Hanna M, Banks E, et al. The Genome Analysis Toolkit: A MapReduce framework for analyzing next-generation DNA sequencing data. Genome Research. 2010;20(9):1297–1303. doi:10.1101/gr.107524.110
  • Poplin R, Ruano-Rubio V, DePristo MA, et al. Scaling accurate genetic variant discovery to tens of thousands of samples [Preprint]. bioRxiv. 2017:201178. doi:10.1101/201178
• Picard

Data

• GRCh38 (Genome Reference Consortium)
  • Schneider VA, Graves-Lindsay T, Howe K, et al. Evaluation of GRCh38 and de novo haploid genome assemblies demonstrates the enduring quality of the reference assembly. Genome Research. 2017;27(5):849–864. doi:10.1101/gr.213611.116
• PharmCAT's GRCh38 reference FASTA
  • Woon M. GRCh38.p13 Reference FASTA (bgzip'd with faidx) [Data set]. Zenodo; 2022. doi:10.5281/zenodo.7288118
• UCSC hg38
  • Casper J, Speir ML, Raney BJ, et al. The UCSC Genome Browser database: 2026 update. Nucleic Acids Research. 2026;54(D1):D1331–D1335. doi:10.1093/nar/gkaf1250
• 1000 Genomes GRCh38 analysis set
  • Zheng-Bradley X, Streeter I, Fairley S, Richardson D, Clarke L, Flicek P; 1000 Genomes Project Consortium. Alignment of 1000 Genomes Project reads to reference assembly GRCh38. GigaScience. 2017;6(7):1–8. doi:10.1093/gigascience/gix038
• GRCh37
  • Church DM, Schneider VA, Graves T, et al. Modernizing Reference Genome Assemblies. PLOS Biology. 2011;9(7):e1001091. doi:10.1371/journal.pbio.1001091
• UCSC hg19ToHg38 chain
  • Hinrichs AS, Karolchik D, Baertsch R, et al. The UCSC Genome Browser Database: update 2006. . 2006;34(Database issue):D590–D598. doi:

Licenses and terms of use: Credits.

This project was originally inspired by software such as NeuroPGx, available here: https://github.com/Andreater/NeuroPGx

• Zampatti S, Fabrizio C, Ragazzo M, et al. Precision Medicine into Clinical Practice: A Web-Based Tool Enables Real-Time Pharmacogenetic Assessment of Tailored Treatments in Psychiatric Disorders. Journal of Personalized Medicine. 2021;11(9):851. doi:10.3390/jpm11090851

License

This project is provided under the AGPLv3 License.

Copyright (C) 2024-2026 Iliya Yaroshevskiy