bbi-js

Parser for BigWig and BigBed file formats.

Install

npm install @gmod/bbi

Usage

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

const local = new BigWig({ path: 'volvox.bw' }) // node only

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

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

@gmod/range-cache-filehandle merges adjacent reads and answers repeat reads from memory. new BigWig({ url }) also works, without that cache.

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>

Note that such CDN usage makes you reliant on a third party service, esm.sh, staying up, so it's not necessarily recommended for production usage, but it does work

See the example folder for a complete working demo.

Decompression

A Rust/WebAssembly libdeflater module, inlined in the bundle as base64, inflates the blocks at ~2.5–3× a pure-JS inflate, so there is nothing extra to install or configure. See docs/wasm.md.

Docs

• docs/api.md — constructor, options, methods, types, BigWig/BigBed and helpers
• docs/optimizations.md — decisions we made to improve performance
• docs/concurrency.md — how many range requests a query makes
• docs/parser-selection.md — decision tree showing decoding workflow
• docs/wasm.md — description of the Rust/WebAssembly decompressor

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