bni

bni builds and queries a read-name index for BAM files sorted with samtools sort -N.

• Prototype C implementation
• File format: BNIv1
• Input: BGZF-compressed BAM
• Required sort order: queryname:lexicographical

• C compiler
• htslib development headers and library
• zlib / bzip2 / lzma as required by your htslib build

With a system htslib available via pkg-config:

make

With a local htslib source/build tree:

make HTSLIB_DIR=/path/to/htslib

Build outputs:

bni
libbni.a
libbni.dylib    # macOS
libbni.so       # Linux

Install:

make install PREFIX=$HOME/.local

samtools sort -N -o reads.name.bam reads.bam
bni index reads.name.bam
bni get reads.name.bam 'READ_ID' > one_read.bam

Additional checks and metadata:

bni stats reads.name.bam
bni check --full reads.name.bam

Default index path:

reads.name.bam.bni

BNIv1 stores one entry per BGZF block that contains BAM record starts.

Each entry stores:

first_qname
last_qname
beg_voff
end_voff
n_records

Lookup uses the first entry whose last_qname >= target_qname, seeks to beg_voff, and scans forward until the target QNAME is found and passed.

• CLI usage
• Library API
• BNIv1 file format

• Input is BAM only.
• Input must be BGZF-compressed and seekable.
• Input must be sorted with samtools sort -N.
• CRAM input is not supported in BNIv1.
• Index entries are loaded into memory; the string table is mmap-backed when available.

bni is inspired by Jared Simpson's bri.