Introducing GenomeScope
GenomeScope is a local app for exploring your own whole-genome sequencing data. It indexes your gVCF for instant lookups, builds an annotated clinical variant catalog, verifies it against a local ClinVar release, and joins live NCBI lookups with your own genotypes.
GenomeScope is a new app for exploring your own whole-genome sequencing data on your own machine. You give it a single-sample GRCh38 gVCF — plus structural-variant and copy-number VCFs if you have them — and it turns that into a searchable, annotated clinical variant catalog you can browse in a local web UI.
It is research-grade interpretation, not a medical diagnosis; anything clinically relevant should be confirmed with an accredited laboratory.
What it does
Starting an analysis runs a five-stage pipeline, with live progress and a log you can watch:
- Stage the upload — the VCF signature, sample column and genome build are checked (GRCh37 files are rejected).
- Index the gVCF — a sparse byte-offset index over the file resolves any
chr:positionin under two milliseconds by binary search, covering both explicit variant calls and gVCF homozygous-reference blocks. - Build the catalog — every read is annotated with ClinVar, dbSNP and gnomAD data from MyVariant.info and gene data from mygene.info, into a SQLite catalog.
- ClinVar verification — optionally, every carried allele is checked against a locally cached, MD5-verified ClinVar release. The match is allele-specific, not just position-matched.
- Package — the catalog CSV, carried variants, a JSON summary and the ClinVar reports go into a downloadable ZIP.
The explorer
Once an analysis completes, the explorer gives you an 11-field clinical filter matrix over the catalog — RCV ID, chromosome, position, variant ID, gene, risk frequency, variant type, carrier status, condition, classification and evidence — plus presets like "Carried Clinical Findings" and "Pathogenic / Likely Pathogenic". Clicking a row opens an inspector with the allele read-balance bar, read depth and genotype quality, and the exact raw VCF line with its neighboring reads. A separate tab streams raw VCF reads at any coordinate directly from your files.
Identifiers that aren't in the catalog — an rsID, RCV accession, gene or locus — are resolved live: MyVariant.info first, then an NCBI ClinVar import, so new rows appear for things that were never indexed.
Live NCBI lookups
A dedicated tab talks to NCBI's live services — ClinVar, dbSNP, Gene and PubMed over E-utilities and Variation Services — and joins every result with your own genotype read at the same GRCh38 locus. Three modes:
- ClinVar search with free-text terms, showing the translated query actually sent.
- Gene panel scans — pick a gene and a significance tier, and it lists the ClinVar variants you carry first.
- Variant lookup by rsID, RCV, VCV or
chr:position, with ClinVar cards, dbSNP population frequencies, the gene record and publications.
Selected results can be imported into the catalog, and a catalog row can be synced from NCBI when its fields disagree with the live record. All NCBI calls are rate-limited, cached and fault-tolerant — a failure shows up as a notice, never a broken page. A status pill shows whether NCBI is reachable and whether you configured an API key.
Privacy by design
- Files never leave your machine. Each analysis runs in its own folder under the system temp directory, owner-only on macOS and Linux — never inside the repository. Uploads are renamed to canonical names, so kit or sample IDs in file names can't leak into reports.
- Retention is automatic. Finished analyses are deleted after seven days by default; you can delete or discard one at any time.
- The API is local-only. It answers only on
127.0.0.1/localhostwith a Host allow-list against DNS rebinding, requires a custom header on every state-changing request, and sendsCache-Control: no-store. - Offline mode exists. Setting
GENOMESCOPE_OFFLINE=1disables every external lookup; external calls only ever send variant identifiers and coordinates, never files or raw VCF lines.
How it's built
The backend is FastAPI with a job manager that queues analyses and runs each in its own worker subprocess, with crash recovery and a TTL sweep. The core logic lives in a separate package: the VCF engine and indexer, the ClinVar release scanner, and an NCBI client built in three layers — pure parsers, a rate limiter and persistent cache, and the HTTP client itself. The frontend is React 18 + Vite + Tailwind, with three screens: New Analysis, History and the Explorer.
Setup is two commands — setup.sh then run.sh on macOS or Linux (setup.bat / run.bat on Windows) — needing only Python 3.10+ and Node.js 18+. The backend test suite runs fully offline against a synthetic genome, so no real genome data ever touches the repository. Apache 2.0 licensed.