@lipme/vuenomics-visualization-components

Vuenomics Visualization Components

Vue 3 and D3 components to display genomics data (genes, coverage, alignments, variants, sequences, BED regions) as synchronized, zoomable tracks.

Upgrading from 0.x? See MIGRATION.md.

Install

npm install @lipme/vuenomics-visualization-components

Requirements: Vue 3.5+ (peer dependency). The package is published as ES modules only; Node.js 20.19+ can also require() it.

import {
  GenomeAxis,
  GffViewer,
  CovViewer,
  BamViewer,
  VcfViewer,
  VcfMatrixViewer,
  FastaViewer,
  BedViewer
} from '@lipme/vuenomics-visualization-components'
import '@lipme/vuenomics-visualization-components/style.css'

Or register every component globally with the plugin:

import VuenomicsComponents from '@lipme/vuenomics-visualization-components'
app.use(VuenomicsComponents)

The types of the props, events and loaders (Variant, GffFeature, CoverageData, BedFeature, AxisSettings…) are exported from the package root.

Quick start

Tracks are placed inside a GenomeAxis, which draws the coordinates, gives the tracks their width and margins, and keeps their zoom in sync:

<template>
  <GenomeAxis
    :domain="[6380000, 6420000]"
    :right-boundary="7000000"
    :settings="{ width: 1000 }"
    @update-domain="(domain) => console.log('displayed region', domain)"
  >
    <GffViewer :data="genes" :height="200" track-name="Genes" />
    <CovViewer :data="{ forward: coverage }" track-name="Coverage" />
    <VcfViewer :data="variants" track-name="Variants" />
  </GenomeAxis>
</template>

• Tracks zoom with the mouse wheel and pan by dragging; ctrl+drag on the axis selects a region.
• Each GenomeAxis synchronizes only its own tracks: several independent browsers can live on the same page.
• Every track has a height prop (in pixels) and an optional trackName. Their width and margins are those of the axis.

Common events

Loading data from indexed files

The loaders read a region from bgzipped, indexed files served over HTTP (range requests). Each file is opened once: its index and header are downloaded on the first request only, and the readers are only loaded when a loader is first used.

import { getVcf, getFasta, getGff, clearDataCache } from '@lipme/vuenomics-visualization-components'

// coordinates: 0-based start, end excluded
const variants = await getVcf('https://example.org/data.vcf.gz', 'chr1', 10000, 20000)
const sequence = await getFasta('https://example.org/genome.fa.gz', 'chr1', 10000, 20000)
const features = await getGff('https://example.org/genes.gff3.gz', 'chr1', 10000, 20000)
clearDataCache() // forget the opened files, e.g. after they changed on the server

The last argument is an optional options object:

• tbiUrl (getVcf, getGff), faiUrl and gziUrl (getFasta): URLs of the indexes. They default to the file URL followed by .tbi, .fai and .gzi.
• signal: an AbortSignal, to cancel the load of a region that is no longer displayed.

const controller = new AbortController()
getVcf(url, 'chr1', 10000, 20000, { tbiUrl: `${url}.tbi`, signal: controller.signal })
controller.abort()

Serve the files without Content-Encoding: gzip (some servers add it for .gz files, which breaks range requests): the .bgz extension avoids it.

getGff returns the GFF3 features with their child features. The GffViewer also needs the level (row) of each feature, in its place field.

Components

GenomeAxis

Slots: default (the tracks) and screenshot, whose screenshotFunction prop saves the axis and its tracks as a PNG image.

<GenomeAxis :domain="region" :right-boundary="chromosomeLength">
  <!-- tracks -->
  <template #screenshot="{ screenshotFunction }">
    <button @click="screenshotFunction">Take a screenshot</button>
  </template>
</GenomeAxis>

GffViewer

Displays GFF3 features and their child features (mRNA, CDS, UTRs…).

<GffViewer
  :data="genes"
  :color-service="new TypeColors({ gene: 'teal', mRNA: 'orange', unknown: 'gray' })"
/>

CovViewer

Displays the coverage of the forward strand, and optionally of the reverse strand (negative scores).

BamViewer

Draws alignments on a canvas, with their insertions, deletions and mismatches.

VcfViewer

Displays variants, colored by type (SNV, insertion, deletion) or by a coloring strategy.

Two coloring strategies are provided:

import { colorByThreshold, colorByValue } from '@lipme/vuenomics-visualization-components'

// color of the largest of the HET, HOM, NC and WT INFO fields
const byGenotypes = {
  colorInfo: { HET: 'green', HOM: 'blue', NC: 'black', WT: 'red' },
  strategy: colorByThreshold
}
// color of the first regular expression matching the value of an INFO field
const byEffect = {
  field: 'ANN',
  colorInfo: {
    high: { regex: '\\|HIGH\\|', color: 'crimson' },
    low: { regex: '\\|LOW\\|', color: 'gray' }
  },
  strategy: colorByValue
}

VcfMatrixViewer

Displays the genotype of each sample for each variant.

FastaViewer

Displays a sequence and its complement when the visible region is small enough.

BedViewer

Displays BED regions, colored by score (or by strand without score), with strand arrows.

Development

VSCode with the Vue extension is recommended.

Mock data:

• src/mocks/*.json: genes, coverage, alignments and GFF colors.
• public/mock-data/: a synthetic bgzipped FASTA (.fai, .gzi), a tabix-indexed VCF and a tabix-indexed GFF3, read through HTTP range requests with the same loaders as an application. Restart npm run dev after regenerating them.

The bgzipped files use the .bgz extension: static servers usually send Content-Encoding: gzip for .gz files, which makes the browser decompress the requested byte ranges and breaks the indexed readers. The public/ folder is not copied into the library build.