bbi-js

Parser for BigWig and BigBed file formats.

Install

npm install @gmod/bbi

Usage

import { BigWig } from '@gmod/bbi'
import { RemoteFile } from 'generic-filehandle2'

const local = new BigWig({ path: 'volvox.bw' }) // node only
const remote = new BigWig({ url: 'https://example.com/file.bw' })
const custom = new BigWig({
  filehandle: new RemoteFile('https://example.com/file.bw'),
})

const header = await remote.getHeader()
const features = await remote.getFeatures('chr1', 0, 100_000)

A bigwig query reads a few R-tree index nodes and then the data blocks they point at. Those reads are small and clustered: panning twenty half-overlapping windows across the test file issues 23 of them, and all 23 land inside four 256 KiB chunks. Passing @gmod/range-cache-filehandle as the filehandle collapses them to those four fetches, and serves a repeat query from memory:

import { RemoteFileWithRangeCache } from '@gmod/range-cache-filehandle'

const cached = new BigWig({
  filehandle: new RemoteFileWithRangeCache('https://example.com/file.bw'),
})

Browser (CDN)

<script type="module">
  import { BigWig } from 'https://esm.sh/@gmod/bbi'

  const file = new BigWig({ url: 'https://example.com/file.bw' })
  const features = await file.getFeatures('chr1', 0, 100)
  console.log(features)
</script>

See the example folder for a complete working demo.

Decompression

A Rust/WebAssembly libdeflater module inflates the blocks, at ~2.5–3× a pure-JS inflate and roughly 4–11× the browser's own DecompressionStream. It is base64-inlined into the bundle and loads lazily — nothing to install or configure. One of four parsers then reads the records, two in JS and two fused into the wasm call, chosen from the file's compression, the reader you called and the region count. All four produce the same features.

Migrating to v10

• renameRefSeqs is gone. Map chromosome names at the call site instead; see docs/api.md.
• RequestOptions.headers is gone. It only ever applied to header and index reads, never to feature blocks, and per-request headers do not fit the block-level caching. Set headers on the filehandle instead; see docs/api.md.

Docs

• docs/api.md — constructor, options, every read method, the Feature type, BigBed and the helpers
• docs/optimizations.md — where a query's time goes, and the decisions that follow from it
• docs/concurrency.md — how many range requests a query makes, and the measured effect of overlapping them
• docs/parser-selection.md — which of the four record parsers a call reaches, and why each exists
• docs/wasm.md — the Rust/WebAssembly decompressor
• CONTRIBUTING.md — development, release and publishing

Academic Use

Written with NHGRI funding as part of JBrowse. If you use this in a publication, please cite the most recent JBrowse paper at jbrowse.org.

License

MIT © Colin Diesh