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.

Some author3 min read

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:

  1. Stage the upload — the VCF signature, sample column and genome build are checked (GRCh37 files are rejected).
  2. Index the gVCF — a sparse byte-offset index over the file resolves any chr:position in under two milliseconds by binary search, covering both explicit variant calls and gVCF homozygous-reference blocks.
  3. 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.
  4. 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.
  5. 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 / localhost with a Host allow-list against DNS rebinding, requires a custom header on every state-changing request, and sends Cache-Control: no-store.
  • Offline mode exists. Setting GENOMESCOPE_OFFLINE=1 disables 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.