BAMWhat

A fast Rust CLI that turns an unfamiliar BAM, SAM, or CRAM file into an evidence-backed identity card.

It extracts header metadata, inventories optional tags, measures alignment characteristics, and infers the likely assay, sequencing technology, reference build, and aligner. 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

Use

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

Install the native command from PyPI and run it normally:

pip install bamwhat
bamwhat sample.bam

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.0.

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