Reads block-gzipped (BGZF) files, such as those created by bgzip, using coordinates from the uncompressed file.

Uses WASM (libdeflate) for decompression. Used by @gmod/indexedfasta for bgzip-indexed FASTA files with gzi index, and also @gmod/bam and @gmod/tabix for block decoding.

Install

$ npm install @gmod/bgzf-filehandle

Usage

BgzfFilehandle

Read from a bgzip-compressed file with a .gzi index as if it were uncompressed:

import { BgzfFilehandle } from '@gmod/bgzf-filehandle'
import { LocalFile } from 'generic-filehandle2'

const f = new BgzfFilehandle({
  filehandle: new LocalFile('path/to/my_file.gz'),
  gziFilehandle: new LocalFile('path/to/my_file.gz.gzi'),
})

// note: read(length, position) — matches generic-filehandle2 convention
const data = await f.read(300, 0) // => Uint8Array

unzip

Decompress an entire BGZF-compressed buffer. Also handles plain gzip:

import { unzip } from '@gmod/bgzf-filehandle'

const decompressed = await unzip(compressedData)

unzipChunkSlice

Decompress a range of BGZF blocks and slice out a virtual file offset range (used by BAM/tabix readers with BAI/TBI indices):

import { unzipChunkSlice } from '@gmod/bgzf-filehandle'

const { buffer, cpositions, dpositions } = await unzipChunkSlice(
  compressedData,
  chunk, // { minv: { blockPosition, dataPosition }, maxv: { blockPosition, dataPosition } }
)

The returned cpositions and dpositions give the block boundaries in compressed and decompressed coordinates, which can be used for generating stable feature IDs across chunk boundaries.

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.

Publishing

Trusted publishing via GitHub Actions.

npm version patch  # or minor/major

License

MIT © Robert Buels