genomeOS

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.

Document	What it covers
Project overview	Start here. Motivation, vision, goals, data sources, how to contribute
Contributing · Agent contract	How to submit code or data, and every rule CI enforces
Literature evidence curation	The contract for submitting publication measurements, column by column
Atlas v1 design spec	The full technical design for sub-projects P0–P5
Implementation plan 1	Task-by-task plan for the data foundation (P0 + P1)
Pan-UKB architecture	The serving model for the GWAS evidence layer
Board conventions	Labels, priorities, milestones, automation
Deployment guide · gcloud wrapper	GCP operations
Data store

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.

1. Introduce yourself in Discussions.
2. Read the overview, which ends with a per-skill list of the issues that actually block progress.
3. 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.
4. 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.