Metadata-Version: 2.4
Name: bamwhat
Version: 0.2.3
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
License-File: LICENSE
Summary: Fast, evidence-backed inspection of BAM, SAM, and CRAM files
Keywords: bam,sam,cram,bioinformatics,nanopore
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# 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:

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

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

```bash
sudo apt install build-essential pkg-config libssl-dev zlib1g-dev \
  libbz2-dev liblzma-dev libcurl4-openssl-dev
```
## Install
pip it!
```bash
pip install bamwhat
```

## Use

```bash
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

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

## License

MIT

