An open atlas of human genetic variation — across the world's populations, and inside the
cell — where every number can be traced back to the measurement behind it.
Why
Any two people's DNA differs in a few million places. Almost all of those differences do
nothing. A small number cause disease, protect against it, or decide whether a medicine will
work or cause harm — and they are not spread evenly around the world.
Take the sickle-cell change. Inherit one copy and you are healthy and substantially protected
against severe malaria; inherit two and you have
sickle-cell anaemia. So it is
common where malaria was historically widespread, and rare elsewhere — and knowing how common,
where, tells health services how many children will be born with the condition and whether to
screen for it. A research team spent years building exactly that map, and published an estimate
of around 300,000 affected births a year with honest error bars
(Piel et al., The Lancet, 2013).
That has been done properly for roughly two genetic changes. For the thousands of others —
cystic fibrosis,
Tay-Sachs, the
thalassaemias, and the many
variants that determine whether a common drug is safe for you — nobody can tell you how common
they are where you live. The data is scattered; the largest open collection of human variation
(gnomAD) covers 800,000 people but records their origins
only as broad continental labels, which cannot be put on a map; and producing an honest answer
is genuinely hard, because a smoothly coloured map is very good at looking confident about
guesses.
We think it should be a map you can open in a browser.
What we are building
- A world map of genetic variation — where a variant was actually measured, an estimate of
how common it is everywhere else with explicit uncertainty, a clear marking of everywhere we
don't know, and what that implies in terms of real people: expected carriers and affected
individuals, with credible intervals.
- A time slider over that map, driven by thousands of georeferenced ancient genomes
(AADR) —
allele frequency across the last ten thousand years. Nobody has shipped this.
- A 3D atlas of the genome inside the cell — from the nucleus, into chromosome territories,
into chromatin domains and loops, down to individual genes.
- The bridge between them — go from a gene's physical context in the nucleus out to where
its variants are common in the world, without leaving the system. Both halves exist
separately today. The connection does not.
How it is different
A colour-coded world map of "genetic disease burden" is one of the most misusable objects you
could build in this field, and interpolation between sparse measurements will happily
manufacture convincing patterns that have no cause. So a few properties are built in as
invariants rather than added as disclaimers:
- What was measured and what was estimated are never mixed — separate tables, separate
layers, separate provenance.
- Every map shows where it doesn't know. Unmapped areas are hatched, on by default, and
excluded from every summary statistic — and the unmapped fraction is reported with the answer.
- Zooming in never invents detail. Resolution follows data density, not zoom level.
- When the data won't support a number, we publish no number and say why.
- Scope is enforced server-side: v1 covers single-gene conditions and drug-response variants
with formal clinical guidelines. Behavioural, cognitive and anthropometric traits are excluded
from burden mapping, for every caller, by the API rather than by policy someone might forget.
And the bar for v1 is reproducing published science, not shipping a demo: the pipeline must
independently arrive at the Lancet sickle-cell numbers, at Howes et al.'s G6PD numbers, and at
carrier rates that national screening programmes have already measured directly. Failing those
tests blocks publication of anything else.
Status
| |
|---|
| Atlas | P0/P1 data contracts and adapters, P2 surface kernels, P3 burden kernels, and a fixture-backed P4 read path are implemented. The diagnostic preview proves browser → API → DuckDB → immutable Parquet; it is not the product map. |
| Pan-UKB evidence API | Running. Provenance-first API over Pan-UK Biobank metadata and selectively indexed ancestry-stratified GWAS associations — the trait and effect-size layer of the atlas. Full summary-statistics files stay in public object storage and are queried by genomic region through a Tabix boundary. |
Documentation
New here? Start with the project overview — what this is, why it
matters, the specific goals, and how to contribute. The first half assumes no genetics
background; there is a glossary at the end.
Getting the data
The data is open: the fitted surfaces, validation evidence and curated inputs are in a public data
store at https://storage.googleapis.com/genomeos-atlas-data/, with no credentials needed. Git keeps only a checksummed manifest per release
(data/releases/); the store's own copy is at manifests/<release>.json under that URL. Clone
without the historical data blobs, then fetch what you need:
git clone --filter=blob:none https://github.com/genomeOS/genomeOS.git && cd genomeOS
python scripts/fetch_data.py # every file sha256-verified against the manifest
Details, including what is not published yet (trained models, raw third-party harvests), are in
the data store guide.
Contributing
Contributors from every background are welcome — this needs population geneticists, spatial
statisticians, clinical geneticists, data and frontend engineers, governance expertise, and
people who can open doors to datasets.
- Introduce yourself in Discussions.
- Read the overview, which ends with a per-skill list of the issues
that actually block progress.
- Check the issues — open
and closed. Open issues are the work queue; closed ones record what was already done and
what was considered and rejected, so search before starting anything.
- Pick something up from the project board.
Filter by
skill:* to find what you can do; Ready means fully specified and unblocked, so
take it without asking.
Before writing code or submitting data, read CONTRIBUTING.md — it is a
short router to the doc for your workstream and the gates CI enforces — and then
AGENTS.md, which is the contract. Data contributions have a stricter bar than code,
because a wrong number is harder to detect than a broken build and can be cited before anyone
notices; CONTRIBUTING.md says what that bar is.
Found a bug, or want a feature? Open an issue. Features get triaged before implementation —
priority here is derived from the dependency graph, so please don't arrive with an unrequested
feature PR. All changes to the repository go through a pull request, including docs.
Issues labelled wants-expert-review are the highest-leverage contribution a specialist can
make — you don't have to write the code to make the difference. Corrections to the design, the
dataset scores, and the statistics are actively wanted.
Run the published container
The public genomeOS package on GitHub Container Registry
provides native linux/amd64 and linux/arm64 images and does not require a GitHub login. To run
the latest image whose main commit passed CI:
docker pull ghcr.io/genomeos/genomeos:latest
docker run --rm --read-only --tmpfs /tmp \
-e DATABASE_URL=sqlite:////tmp/genomeos.db \
-e ATLAS_ARTIFACT_ROOT=/app/demo/artifacts \
-p 127.0.0.1:8000:8080 \
ghcr.io/genomeos/genomeos:latest
In another terminal, check readiness and open the diagnostic preview:
curl http://127.0.0.1:8000/ready
open http://127.0.0.1:8000/preview # macOS; use xdg-open on Linux
For a reproducible run, pin the image to a seven-character commit tag (the package page lists
them) instead of latest. Replace sha-xxxxxxx below with one of those tags:
TAG=sha-xxxxxxx
docker pull "ghcr.io/genomeos/genomeos:$TAG"
docker run --rm --read-only --tmpfs /tmp \
-e DATABASE_URL=sqlite:////tmp/genomeos.db \
-e ATLAS_ARTIFACT_ROOT=/app/demo/artifacts \
-p 127.0.0.1:8000:8080 \
"ghcr.io/genomeos/genomeos:$TAG"
Images published before the repository moved to the genomeOS organization (for example
sha-813edd0) were not copied and stay pullable at their old address,
ghcr.io/bschilder/genomeos.
latest advances only after the required CI workflow succeeds on main; sha-... tags do not
move. Each multi-architecture manifest includes OCI revision metadata, an SBOM, and provenance
attestations. The container runs as an unprivileged user with a read-only filesystem; /tmp is
the only writable location and holds the disposable diagnostic database. The bundled artifacts
are tiny synthetic fixtures for checking the read path—they are not scientific results. See the
deployment guide for production data, database, and Cloud Run
requirements.
Local development
python -m pip install -e '.[dev,read]'
genomeos init-db
uvicorn genomeos.api:app --reload
python scripts/http_smoke.py --base-url http://127.0.0.1:8000
Open http://127.0.0.1:8000/preview for the infrastructure
preview. The checked-in demo artifacts are synthetic and diagnostic; they are not scientific
results. Run python scripts/smoke.py after changes and the full pytest suite before a PR.
By default the service uses sqlite:///./genomeos.db and demo/artifacts for local development.
Production requires a PostgreSQL DATABASE_URL and an explicit ATLAS_ARTIFACT_ROOT. GCP
operations must use the
repository-local gcloud wrapper.
License
Except where stated otherwise, project-authored source code and documentation in this repository
are licensed under the Apache License 2.0.
Third-party datasets, model outputs, and bundled components are not relicensed by this notice.
Their source-specific terms remain controlling and are recorded in the relevant provenance,
licence, or notice files. See non-commercial data policy for how
genomeOS keeps restricted inputs separable.
