qbix

qbix indexes and retrieves BAM records by QNAME (read name) using a .qbi index.

Use it when you need records for one or more QNAMEs from a BAM file without scanning the file.

The index stores:

• XXH3-64 hashes of QNAMEs
• BGZF virtual offsets
• BAM size, mtime, and header hash for stale-index detection

The .qbi file format is documented in docs/qbi-format.md.

qbix was inspired by jts/bri. .qbi is not compatible with .bri. .qbi stores QNAME hashes and BGZF virtual offsets instead of names. Lookup candidates are checked against BAM QNAME before output.

Install

Download a prebuilt binary from GitHub Releases.

Build From Source

Requirements:

• Rust and Cargo
• htslib
• pkg-config recommended

Install htslib and pkg-config with your system package manager:

# macOS
brew install htslib pkg-config

# Ubuntu/Debian
sudo apt-get install libhts-dev pkg-config

cargo build --release

The binary is:

target/release/qbix

If htslib is installed under a custom prefix:

HTSDIR=/path/to/htslib cargo build --release

For static htslib linking:

HTSLIB_STATIC=1 cargo build --release

Optional colored SAM output uses libbiosyntax, which is GPL-3.0-only. It is disabled by default. Enable it explicitly if that license is acceptable:

cargo build --release --features biosyntax

With this feature enabled, the build downloads libbiosyntax v0.1.0 into Cargo's build directory. To use an existing checkout instead:

LIBBIOSYNTAX_DIR=/path/to/libbiosyntax cargo build --release --features biosyntax

You can also build and install from crates.io:

cargo install qbix

The crates.io install builds from source and expects htslib headers and libraries to be available on the system.

Basic Use

Create an index:

qbix index reads.bam

This writes:

reads.bam.qbi

Fetch records by QNAME. Output is SAM:

qbix get reads.bam read_a read_b

Fetch records from a newline-delimited read-name file:

qbix get reads.bam -f names.txt

Use -f - to read names from stdin:

cat names.txt | qbix get reads.bam -f -

Write matching records as BAM:

qbix get reads.bam -f names.txt -b -o hits.bam
qbix get reads.bam -f names.txt -Ob -o hits.bam

When built with --features biosyntax, SAM output to a terminal is colored by default. Pipes and files are left plain. Use --color always or --color never to override:

qbix get --color always reads.bam read_a
qbix get --color never reads.bam read_a

Use more htslib threads:

qbix index -@ 4 reads.bam
qbix get -@ 4 reads.bam read_a

Use an explicit index path:

qbix index -i reads.qbi reads.bam
qbix get -i reads.qbi reads.bam read_a

Output Order

Default output is query order:

qbix get reads.bam read_a read_b
qbix get --query-order reads.bam read_a read_b

Query-order output streams lookups without collecting all hits in memory.

For multiple read names, --bam-order reads records in BAM file-offset order. This can reduce random seeking:

qbix get --bam-order reads.bam read_a read_b

--bam-order must collect and sort matching hits before output.

If name-sorted output is needed, sort downstream:

qbix get --bam-order reads.bam read_a read_b | samtools sort -N -O SAM -

Other Commands

Quickly check that an index matches its BAM size, mtime, and header hash:

qbix check reads.bam
qbix check --quick reads.bam

check defaults to --quick. Use --full to also seek to every indexed record and verify its read-name hash:

qbix check --full reads.bam

Print records-per-read-name statistics from the index. stat is accepted as an alias for stats:

qbix stats reads.bam
qbix stat reads.bam
qbix stats -i reads.qbi reads.bam

Use JSON output for scripts:

qbix stats --json reads.bam

Show raw index rows:

qbix show reads.bam.qbi

show prints:

qhash<TAB>voff

Print the version:

qbix --version

Notes

• .qbi files are tied to the BAM size, mtime, and header hash.
• Rebuild the index after replacing or rewriting the BAM.
• Read names are not stored in the index. Hash hits are verified against the BAM record QNAME before output.

Rust Library

qbix also exposes a small Rust API:

let index_path = qbix::build_index("reads.bam", qbix::BuildOptions::default())?;
qbix::check_index("reads.bam", qbix::CheckOptions::default())?;
qbix::check_index(
    "reads.bam",
    qbix::CheckOptions {
        mode: qbix::CheckMode::Full,
        ..qbix::CheckOptions::default()
    },
)?;
let bam = qbix::IndexedBam::open("reads.bam", qbix::LookupOptions::default())?;
let hits = bam.lookup("read_a")?;

C Library

qbix can be built as a C library from source:

cargo build --release

Libraries are written under target/release, for example libqbix.so, libqbix.a, or libqbix.dylib. The header is include/qbix.h.

For HTSlib-based applications, build qbix against the same HTSlib installation as the host application. C API errors are stored per calling thread. qbix_index_t handles are not thread-safe.

Example:

#include "qbix.h"

int main(void) {
    qbix_hit_t *hits = 0;
    size_t n_hits = 0;

    if (qbix_build_index("reads.bam", 0, 1) != 0) return 1;
    if (qbix_check_index("reads.bam", 0, 1, QBIX_CHECK_QUICK) != 0) return 1;

    qbix_index_t *idx = qbix_index_open("reads.bam", 0, 1);
    if (!idx) return 1;

    if (qbix_index_lookup(idx, "read_a", &hits, &n_hits) == 0) {
        qbix_hits_free(hits, n_hits);
    }

    qbix_index_close(idx);
    return 0;
}