Python · Domain-Driven Design · Hexagonal Architecture
A domain model for genomic variant analysis
Built to hold up at clinical cohort scale.
iris provides the semantic layer that lets genomic tools compose coherently.
uv add 'iris[genomics]'The problem
Every pipeline reinvents the same coordinate logic
Genomic pipelines run on a dozen excellent, isolated tools — bcftools, VEP, CADD, dbNSFP, ClinVar lookups — each with its own coordinate conventions, file formats, and notion of what a “variant” is.
The work of reconciling them falls on bioinformaticians, who rewrite the same coordinate-translation and normalization logic in every pipeline, in the most fragile form possible: positional string manipulation with no tests and no version history.
The model
The semantic layer between your tools
iris is a Python library that provides the missing semantic layer: a rigorous, versioned, testable domain model of genomics — variants, genes, annotations, clinical classifications, filters — built with Domain-Driven Design and Hexagonal Architecture.
It does not replace bcftools, VEP, or GATK. It is the layer that lets them compose coherently.
Pure domain, explicit ports
Domain objects carry no infrastructure dependencies; adapters implement the ports the domain defines.
Immutable by construction
Frozen, versioned domain objects — no hidden state mutation to trace through a pipeline.
Testable independent of format or database
Domain logic is verified without a VCF file, a running database, or a live pipeline.
Why now: clarity and efficiency
The same discipline that makes it auditable makes it fast
iris's domain model is deliberately pure and immutable — frozen attrs classes, zero infrastructure dependencies. That discipline is what makes it testable and auditable. It also turns out to be what makes it efficient.
Parallel extraction
Region extraction runs in parallel by default (ThreadPoolExecutor + GIL-releasing Zarr reads), scaling close to linearly with worker count.
Predicate pushdown
The uvar population-variant store queries datasets up to ~46 GB per chromosome through Arrow’s predicate pushdown — a single-gene query prunes by row-group statistics instead of scanning the file.
Zero-copy IPC
The Python↔Rust boundary is Apache Arrow IPC: zero-copy, one schema, no serialization tax.
Shared identity
Shared chromosome identity collapses millions of per-variant string objects into one per chromosome across a cohort.
iris was designed as a domain model first. It turned out that a correctly designed domain model is also a fast one — because the same discipline that makes it auditable is what makes it efficient.
Who it’s for
Built for the people who touch the pipeline
Bioinformaticians
Tired of rewriting coordinate-conversion code in every pipeline, in whatever fragile form is fastest to ship.
Platform engineers
Building clinical or research variant-analysis systems that need a foundation testable independent of any one file format or database.
Product owners & clinical domain experts
Need filter logic they can actually read and verify — not reverse-engineer from a pipeline script.
What iris isn’t
- Not a variant caller.
- Not a new annotator.
- Not a wrapper.
- Not a framework — it doesn’t invert control; you call it, not the other way around.
- Not a replacement for bcftools, VEP, or GATK — it’s the layer between them.
Get started
Add iris to your pipeline
uv add 'iris[genomics]'Source, documentation, and architecture notes live in the project repository.