Skip to content

VCF Browser

The VCF browser is the primary interface for variant curation. It surfaces the variants from an order's VCF(s) in a filterable, sortable table and links out to the per-variant detail page.

Backing service

The browser is backed by the VCF service (vcf-service). For each order, the VCF service:

  • Parses the bgzipped + tabix-indexed VCF files attached to the order's samples.
  • Builds an SQLite cache on NVMe storage keyed by the order, so that hundreds of thousands of variants can be filtered and sorted quickly.
  • Serves variant pages over HTTP to the Miner UI.

The cache is built asynchronously on first browser open; subsequent views hit the warmed cache.

Capabilities required

Access to the browser for a given order depends on three things:

  1. The caller's role (minimum project_viewer to view; project_editor to edit).
  2. The current labflow stage's capability flags (browser_viewable, browser_editable).
  3. Assignment — to edit, the caller must be the current stage's assignee (or hold orders:write_any).

If the stage does not permit browsing, the browser page returns a "stage does not allow this action" notice rather than the variant table. See RBAC Matrix.

Assignment required to edit

Even with a sufficient role, variant edits are blocked unless you are assigned to the current stage. Self-assign first, then edit.

Layout

The browser has two columns:

  • Variant table on the left — rows are variants, columns are the key fields (genomic coordinates, HGVS, gene, consequence, tier or ACMG classification, VAF, classification status).
  • Filter panel + detail pane on the right — the currently selected variant's details, and the filter controls.

Filters

Most useful filters in practice:

  • Tier — IA / IB / II / III. Tier IV is hidden by default.
  • VAF — numeric threshold; somatic reviewers often use VAF ≥ 0.05 as a starting point.
  • Gene panel — if the project has a gene panel configured, filter to just the panel's genes.
  • Consequence — non-synonymous, splice, frameshift, etc.
  • Search — HGVS, gene symbol, rsID.

Sorting

Default sort is by tier priority (IA → IB → II → III) and then by position. Click any column header to change the sort.

Pagination

Tables are paginated. For very wide variant sets, prefer narrowing filters before paging through — each page hits the SQLite cache which is fast but scrolling through thousands of variants is not productive.

Clinical actions in the browser

  • Add to report — mark the variant for inclusion; creates a ReportVariantAssociation.
  • Remove from report — reverses the above.
  • Classify — assign the final tier (somatic) or enter ACMG criteria (hereditary).
  • Note — write a per-variant note that will surface on the report.

Each of these requires both an editable stage and assignment. The UI hides the controls when the caller is not authorised.

Filter early, page less

The SQLite cache is fast, but scrolling through thousands of rows is not productive. Narrow your filters (tier + VAF + gene panel) before paging.

Ghost-lock self-heal

The VCF service uses file-level locks to prevent concurrent SQLite builds for the same order. If a pipeline crashes mid-build, the lock can become "ghost"-owned — no running process holds it. iFlow self-heals: on the next request, the service compares the lock timestamp with the running pipelines and clears the lock if no active owner is found. The browser may show a one-time "Rebuilding cache" spinner during recovery.

Export

The VCF browser does not directly export variant tables for distribution (the signed report PDF is the distribution artifact). The CLI offers the closest equivalent:

iflow files list samples/{slug}/uploads/        # locate the raw VCF
iflow files download samples/{slug}/uploads/...  # fetch the raw file