@gmod/twobit
Read .2bit sequence files, in Node.js or the browser.
Install
$ npm install @gmod/twobit
Usage
import { TwoBitFile } from '@gmod/twobit'
const t = new TwoBitFile({ path: 'path/to/file.2bit' })
// coordinates are 0-based half-open
await t.getSequence('chr1', 0, 10) // first 10 bases
await t.getSequence('chr1') // whole sequence
await t.getSequenceNames() // ['chr1', ...]
await t.getSequenceSizes() // { chr1: length, ... }
await t.getSequenceSize('chr1')
In the browser, or for a file over HTTP, pass a filehandle from
generic-filehandle2
instead of a path:
import { RemoteFile } from 'generic-filehandle2'
const t = new TwoBitFile({
filehandle: new RemoteFile('https://example.com/file.2bit'),
})
Reading a sequence takes four reads: the record header and its two block
tables, which come to 32 bytes and sit at the same offsets every time you read
that sequence, then the packed bases. Over HTTP that is four round trips per
sequence, so a byte-range cache such as
@gmod/range-cache-filehandle
is a cheap swap for RemoteFile. It serves reads out of 256 KiB chunks, so the
header reads come from memory after the first one and neighboring sequences
share a request. The index is read once, in chunks sized for typical
sequence names, so a scaffold-level assembly with hundreds of thousands of
sequences costs a few megabytes rather than a read sized for the longest name
the format allows.
Returned sequences preserve the file's encoding: lowercase for soft-masked
bases, N/n for ambiguous ones.
See docs/api.md for the full API reference.
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.
Contributing
See CONTRIBUTING.md for development and release workflow.
License
MIT © Robert Buels