# Graphoscope

> Graphoscope draws pangenome graphs in the browser. It queries the HPRC v2.1 pangenome graphs (GRCh38- or CHM13-based) by gene or coordinates, and also opens any GFA file. Everything it shows is set by URL parameters, so a link reproduces a view exactly. There is no backend: pages run the query (wasm + HTTP range requests) in the browser, so use a JS-capable browser, not curl.

Base URL: https://graphoscope.omgenomics.com/

## Pages

- [Locus browser](https://graphoscope.omgenomics.com/?ref=grch38&locus=SMN1): query an HPRC graph by gene symbol or contig:start-end and draw it.
- [GFA viewer](https://graphoscope.omgenomics.com/gfa?example=mlph): draw a bundled example or any GFA reachable by URL.
- [JSON endpoint](https://graphoscope.omgenomics.com/api?ref=grch38&locus=SMN1): the same query as numbers (node/link/walk counts, variant sites, fetch cost) without drawing anything. `/api` with no locus lists its parameters.

## Waiting for a page to finish

Do not sleep a fixed time. Every page publishes its progress three ways:

- `<html data-status="...">`: `loading` → `querying` → `layout` → `drawing` → `done`, or `error`. Wait for `done` or `error` (e.g. Playwright: `page.waitForSelector('html[data-status=done], html[data-status=error]')`).
- `window.graphoscope`: `{ status, error, warnings, query, complexity, layoutMs, ready }`. `await window.graphoscope.ready` settles at done or error.
- The tab title ends in `· done` (or `· error`), for agents that only see screenshots.

`done` means the query returned, the layout finished, the gene track and marks are drawn, and nothing is animating: take the screenshot then. (`/api` uses `<main data-status>` and `window.graphoscopeResult` instead.)

Layouts are deterministic: the same graph, settings and window size always draw the same picture. Use `size=` to pin the size.

## Locus browser parameters

- `ref`: `grch38` | `chm13`. Default `grch38`.
- `locus`: a gene symbol (`SMN1`, `HLA-A`) or `contig:start-end` (`chr5:70,925,000-70,955,000`; commas are fine). `gene` is an alias. Coordinates must be on the chosen ref's assembly.
- `context`: bp past the locus that haplotypes are followed. Default `10000`.
- `simplify`: pop variants under this many bp (default `50`; the UI offers 50, 100, 250, 500, 1000, 2500, 5000). `off` shows the unsimplified graph when it's small enough.
- `view`: `graph` | `data` (the raw GFA tables). Default `graph`.

## GFA viewer parameters

- `example`: `mlph` (bundled), `fly` (bundled), `drb1`, `mt`, `plasmids`, `tiny`.
- `url`: an http(s) URL of a GFA file. The server must send CORS headers.

## View parameters (both pages)

- `layout`: `stacked` (shown as Strands, the default), `classic` (Skyline), `assembly`, `fm3` (Untangled), `simple-force`, `flow`, `layered` (DAG), `radial`. The shown names work too.
- `theme`: `dark` (default) | `light`. Light is for figures.
- `color`: what node colour encodes: `coverage` (walks through the node; default), `bubbleSize`, `bubble`, `node`, `length`.
- `genes`: `1` | `0`. Draw the gene track. Default `1`.
- `labels`: `1` | `100` | `1kb` | `10kb` | `none`. Label nodes at least this long with their length (the sidebar's Length labels slider). Where labels would overlap, the longer node wins; zoom in with `range` to see more. Default `100`.
- `exits`: `1` | `0`. Locus browser only: cues on haplotypes cut off at the window edge. Default `1`.
- `range`: `contig:start-end`. Zoom to this stretch of reference after layout.
- `select`: a node id. Select it and open its inspector.
- `pin`: a walk to trace: a sample name (pins all its haplotypes), `sample#haplotype`, a full `sample#haplotype#sequence` key, or `Walk 3` for the locus browser's anonymous walks. Repeat it to trace several.
- `msa`: `1` opens the alignment panel under the graph.
- `mark`: `contig:start-end,label`. Draws a labelled amber band over that stretch of reference. Repeat it for several marks. With no `locus`, the first mark's stretch is queried. A mark off screen gets an arrow at the edge; a mark outside the loaded window is reported as a warning.
- `chrome`: `0` hides the header, tabs and options panel, leaving only the graph.
- `size`: `WIDTHxHEIGHT` in px (e.g. `1600x900`). Renders the page at that size regardless of the window, so screenshots are comparable.

Unknown parameters and values that don't parse are not silently dropped: they're listed in a banner on the page and in `window.graphoscope.warnings`.

As you change the view, the address bar is rewritten to match (defaults left out), so the current URL always reproduces what's on screen. Exported PNGs embed that URL in a `Source` text chunk.

## Examples

- A figure with a labelled region: https://graphoscope.omgenomics.com/?ref=grch38&locus=SMN1&mark=chr5:70,940,000-70,941,000,region%20of%20interest&theme=light&chrome=0&size=1600x900
- Two layouts of the same locus: https://graphoscope.omgenomics.com/?ref=chm13&locus=LPA&layout=fm3
- Zoomed in, with the alignment open: https://graphoscope.omgenomics.com/?ref=grch38&locus=HLA-A&range=chr6:29,942,000-29,943,500&msa=1
- A haplotype traced on a bundled GFA: https://graphoscope.omgenomics.com/gfa?example=mlph&layout=strands&pin=HG00438#1
- Complexity numbers only: https://graphoscope.omgenomics.com/api?ref=grch38&locus=SMN1

## Source

- [GitHub repository](https://github.com/marianattestad/graphoscope): parameters are defined in `src/lib/urlState.ts`, the status signal in `src/lib/agentStatus.ts`.