bbi-js

Parser for BigWig and BigBed file formats.

Installation

npm install @gmod/bbi

Usage

Local files

import { BigWig } from '@gmod/bbi'

const file = new BigWig({ path: 'volvox.bw' })
const header = await file.getHeader()
const features = await file.getFeatures('chr1', 0, 100, { scale: 1 })

Remote files

import { BigWig } from '@gmod/bbi'

const file = new BigWig({ url: 'https://example.com/file.bw' })
const features = await file.getFeatures('chr1', 0, 100, { scale: 1 })

You can also pass a custom filehandle from generic-filehandle2:

import { RemoteFile } from 'generic-filehandle2'

const file = new BigWig({
  filehandle: new RemoteFile('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.

API

Constructor (BigWig / BigBed)

Pass exactly one of:

| Option | Description | |---|---| | path | Path to a local file | | url | URL of a remote file | | filehandle | A GenericFilehandle instance from generic-filehandle2 | | renameRefSeqs | Optional (name: string) => string mapping applied to chromosome names before every query — useful when file-internal names differ from query names (e.g. s => s.replace('chr', '')) |

BigWig

getHeader(opts?)

Returns Promise<BigWigHeaderWithRefNames> with chromosome list (refsByName, refsByNumber), zoom levels, summary statistics, and — for BigBed files — the autoSql schema string. The result is cached after the first call.

getFeatures(refName, start, end, opts?)

Returns a Promise<Feature[]> for the given region. Returns an empty array if the refName is not found or the region has no data. Coordinates are 0-based half-open.

| Parameter | Description | |---|---| | refName | Chromosome/sequence name | | start | 0-based start (inclusive) | | end | 0-based end (exclusive) | | opts.scale | Pixels per basepair — selects the zoom level where reductionLevel ≤ 2/scale. Omit for base resolution. | | opts.basesPerSpan | Inverse of scale (basepairs per pixel) | | opts.signal | AbortSignal to cancel the request |

const features = await bigwig.getFeatures('chr1', 0, 100000)
// [{ start, end, score }, ...]

getFeaturesMulti(regions, opts?)

Fetches features for multiple regions in one call. Returns arrays aligned to input order (result[i] corresponds to regions[i]).

Reads for adjacent on-disk blocks are coalesced across region boundaries, so a whole-genome overview needs far fewer range requests than calling getFeatures per region — useful for rate-limited remote files. Regions may be in any order and may overlap.

const perRegion = await bigwig.getFeaturesMulti([
  { refName: 'chr1', start: 0, end: 1_000_000 },
  { refName: 'chr2', start: 0, end: 1_000_000 },
])

getFeaturesAsArrays(refName, start, end, opts?)

Same parameters as getFeatures, but returns typed arrays instead of an array of objects — more memory-efficient and lower GC pressure for large datasets.

const result = await bigwig.getFeaturesAsArrays('chr1', 0, 100000)
// Base resolution: { starts: Int32Array, ends: Int32Array, scores: Float32Array, isSummary: false }

const summary = await bigwig.getFeaturesAsArrays('chr1', 0, 100000, { scale: 0.01 })
// Zoom level:    { starts, ends, scores, minScores: Float32Array, maxScores: Float32Array, isSummary: true }

The isSummary discriminant lets TypeScript narrow the union type:

if (result.isSummary) {
  // minScores and maxScores are available here
}

Types:

interface BigWigFeatureArrays {
  starts: Int32Array
  ends: Int32Array
  scores: Float32Array
  isSummary: false
}

interface SummaryFeatureArrays {
  starts: Int32Array
  ends: Int32Array
  scores: Float32Array
  minScores: Float32Array
  maxScores: Float32Array
  isSummary: true
}

Understanding zoom levels

scale (pixels per basepair) controls which pre-computed zoom level is served. The file stores zoom levels at increasing reductionLevel values; the library picks the first level where reductionLevel ≤ 2/scale, scanning from the coarsest zoom inward:

[
  { "reductionLevel": 40 },
  { "reductionLevel": 160 },
  { "reductionLevel": 640 },
  { "reductionLevel": 2560 },
  { "reductionLevel": 10240 },
  { "reductionLevel": 40960 },
  { "reductionLevel": 163840 }
]

If no zoom level matches (e.g. scale: 1), base-resolution data is returned.

Feature type

Both BigWig and BigBed return Feature objects. Fields vary by file type and zoom level:

| Field | Present on | Description | |---|---|---| | start | always | 0-based half-open start | | end | always | 0-based half-open end | | score | always | Signal value (BigWig) or BED score (BigBed) | | rest | BigBed | Raw tab-delimited BED columns 4+ | | uniqueId | BigBed | Stable ID from file offset; deduplicates exact copies | | field | BigBed (searchExtraIndex) | Which extra-index column matched | | minScore | zoom data | Minimum score across the summary interval | | maxScore | zoom data | Maximum score across the summary interval | | summary | zoom data | true when the feature comes from a zoom level |

BigBed

getFeatures(refName, start, end, opts?)

Returns a Promise<Feature[]>. No zoom levels — always base resolution.

| Parameter | Description | |---|---| | refName | Chromosome/sequence name | | start | 0-based start (inclusive) | | end | 0-based end (exclusive) | | opts.signal | AbortSignal to cancel the request |

searchExtraIndex(name, opts?)

Searches the BigBed extra indexes (created with -extraIndex in bedToBigBed) for a string match. Returns a Promise<Feature[]> with an additional field property indicating which index matched.

Parsing BigBed features with @gmod/bed

Raw BigBed features contain a rest field with tab-delimited columns 4+. Use @gmod/bed together with the autoSql from the file header to parse them into named fields:

import { BigBed } from '@gmod/bbi'
import BED from '@gmod/bed'

const file = new BigBed({ path: './data/hg18.bb' })
const { autoSql } = await file.getHeader()
const feats = await file.getFeatures('chr7', 0, 100000)
const parser = new BED({ autoSql })
const lines = feats.map(({ start, end, rest, uniqueId }) =>
  parser.parseLine(`chr7\t${start}\t${end}\t${rest}`, { uniqueId }),
)

Raw feature:

{
  "chromId": 0,
  "start": 64068,
  "end": 64107,
  "rest": "uc003sil.1\t0\t-\t64068\t64068\t255,0,0\t.\tDQ584609",
  "uniqueId": "bb-171"
}

Parsed feature:

{
  "uniqueId": "bb-0",
  "chrom": "chr7",
  "chromStart": 54028,
  "chromEnd": 73584,
  "name": "uc003sii.2",
  "score": 0,
  "strand": -1,
  "thickStart": 54028,
  "thickEnd": 54028,
  "reserved": "255,0,0",
  "spID": "AL137655"
}

The uniqueId is derived from the file offset and helps deduplicate exact feature copies.

parseBigWig(bigwig, opts?)

Reads all features from every chromosome at base resolution, skipping chromosomes with no data.

import { BigWig, parseBigWig } from '@gmod/bbi'

const file = new BigWig({ path: 'volvox.bw' })
const results = await parseBigWig(file)
for (const { starts, ends, scores } of results) {
  for (let i = 0; i < starts.length; i++) {
    console.log(starts[i], ends[i], scores[i])
  }
}

Returns Promise<BigWigFeatureArrays[]>, one entry per chromosome with data.

ArrayFeatureView / BigWigFeature

ArrayFeatureView wraps a BigWigFeatureArrays or SummaryFeatureArrays result and exposes a JBrowse-compatible Feature-style interface. BigWigFeature is a single-feature view into an ArrayFeatureView.

import { BigWig, ArrayFeatureView } from '@gmod/bbi'

const file = new BigWig({ path: 'volvox.bw' })
const arrays = await file.getFeaturesAsArrays('chr1', 0, 100000)
const view = new ArrayFeatureView(arrays, 'mySource', 'chr1')

for (let i = 0; i < view.length; i++) {
  console.log(view.start(i), view.end(i), view.score(i))
}

BigWigFeature exposes get(i, key) and toJSON(). Valid keys: start, end, score, refName, source, summary, minScore, maxScore.

Publishing

Trusted publishing via GitHub Actions.

pnpm version patch  # or minor/major

Academic Use

This package was written with funding from the NHGRI as part of the JBrowse project. If you use it in an academic project that you publish, please cite the most recent JBrowse paper, which will be linked from jbrowse.org.

License

MIT © Colin Diesh