BAMWhat

A fast Rust CLI that tells you all you need to know about an unfamiliar BAM, SAM, or CRAM file.

It extracts header metadata, inventories optional tags, measures alignment characteristics, and infers the likely assay, sequencing technology, reference build, and aligner. For Oxford Nanopore data, it reports the Dorado basecaller version from a Dorado @PG VN field, with an explicit version in @RG DS as a fallback. The default fast path reads only 100,000 records and uses bounded memory.

Build

Install a current stable Rust toolchain from https://rustup.rs, then:

cargo build --release
./target/release/bamwhat --help

HTSlib compilation requires a C compiler and common compression development libraries. On Debian or Ubuntu:

sudo apt install build-essential pkg-config libssl-dev zlib1g-dev \
  libbz2-dev liblzma-dev libcurl4-openssl-dev

Install

pip it!

pip install bamwhat

Use

bamwhat sample.bam
bamwhat sample.bam --json
bamwhat sample.bam --sample 1000000 --threads 4
bamwhat sample.bam --full --json > passport.json

The wheel contains the compiled Rust executable; invoking bamwhat does not start a Python interpreter. For a local packaging test, run pip install ..

The JSON schema remains versioned separately from the application and is currently 1.1. The dorado_versions array contains each detected version and whether it came from @PG VN or @RG DS.

basecall_model=...@v4.3.0 in @RG DS identifies the basecalling model version, not the Dorado application version, and is deliberately not reported as a Dorado version.

Performance

• Native HTSlib BAM/SAM/CRAM decoding through rust-htslib
• Optional multithreaded BGZF decompression with --threads
• Bounded-memory streaming
• Early termination after the configured sample
• Release profile uses thin LTO, one codegen unit, and stripped symbols

The current fast path samples the beginning of the alignment stream. A future release can add indexed stratified sampling without changing the report schema.

Test

cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --check

License

MIT