BamNado

High-performance tools and utilities for working with BAM and BigWig files in modern genomics workflows. BamNado is written in Rust for speed and low memory use and provides both a command-line interface and Python bindings.

Overview

BamNado is designed for efficient, streaming manipulation of BAM files and signal tracks. It focuses on fast coverage generation, flexible filtering, and lightweight post-processing of bedGraph and BigWig data.

Common use cases:

• Rapid generation of coverage tracks from large BAM files
• Filtering reads by tags or barcodes to produce targeted BigWigs
• Fragment-aware coverage for ATAC-seq and related assays
• BigWig comparison and aggregation across samples
• Post-processing of binned signal tracks for visualization

Useful in workflows including single-cell and Micro-Capture-C (MCC), and many others.

Documentation: API docs on docs.rs

Features

• High-performance, streaming implementations in Rust
• Cross-platform support (Linux, macOS, Windows)
• BAM → bedGraph / BigWig coverage generation
• Fragment-aware and strand-specific pileups
• Read filtering by mapping quality, length, strand, fragment size, tags, and barcodes
• BigWig comparison (subtraction, ratio, log-ratio)
• BigWig aggregation (sum, mean, median, min, max)
• bedGraph post-processing with collapse-bedgraph
• Python bindings for selected functionality

Installation

Pre-built binaries (recommended)

Download the appropriate binary from the releases page.

After downloading, move to your user bin directory (no root required):

chmod +x bamnado
mv bamnado ~/.local/bin/bamnado

Ensure ~/.local/bin is on your PATH (add to ~/.bashrc or ~/.zshrc if needed):

export PATH="$HOME/.local/bin:$PATH"

Alternatively, you can run the binary directly from the download location:

./bamnado --help

cargo binstall

If you have cargo-binstall installed, this downloads the pre-built binary automatically:

cargo binstall bamnado

Docker

docker pull ghcr.io/alsmith151/bamnado:latest
docker run --rm ghcr.io/alsmith151/bamnado:latest --help

Images are available for linux/amd64 and linux/arm64.

Cargo

If you have Rust installed:

cargo install bamnado

Build from source

git clone https://github.com/alsmith151/BamNado.git
cd BamNado
cargo build --release

Optional dependency: samtools

samtools is not required but is strongly recommended if your BAM files have non-standard or incomplete headers (e.g. files produced by CellRanger). BamNado automatically falls back to samtools view -H to parse the header when the built-in parser fails. Without samtools on your PATH, BamNado will error on such files.

Install via conda or your system package manager:

conda install -c bioconda samtools
# or
brew install samtools

Command-line interface

Getting help

bamnado --help                      # List all commands
bamnado <command> --help            # Help for a specific command

Available commands

Read filtering

All coverage commands share common read filter flags:

Coverage-specific flags

Examples

Generate basic coverage

bamnado bam-coverage \
  --bam sample.bam \
  --output coverage.bedgraph \
  --bin-size 100

Generate high-quality, normalized coverage

bamnado bam-coverage \
  --bam sample.bam \
  --output coverage_hq.bw \
  --bin-size 100 \
  --normalize rpkm \
  --min-mapq 30 \
  --proper-pairs

Extract nucleosome-free regions from ATAC-seq

bamnado bam-coverage \
  --bam atac.bam \
  --output nfr_forward.bw \
  --bin-size 10 \
  --strand forward \
  --min-fragment-len 100 \
  --max-fragment-len 200 \
  --fragment-counts \
  --min-mapq 20

Filter by cell barcode (single-cell)

bamnado bam-coverage \
  --bam possorted_genome_bam.bam \
  --output cell_coverage.bw \
  --bin-size 100 \
  --barcode-allowlist barcodes.txt \
  --fragment-counts

Filter by SAM tag (MCC viewpoint)

bamnado bam-coverage \
  --bam mcc.bam \
  --output BCL2_viewpoint.bw \
  --bin-size 50 \
  --tag VP \
  --tag-value BCL2 \
  --fragment-counts \
  --min-mapq 30

Compare two BigWig files

bamnado bigwig-compare \
  --bw1 sample_treated.bw \
  --bw2 sample_control.bw \
  --comparison log-ratio \
  --pseudocount 1e-3 \
  --threads 6 \
  -o treated_vs_control.bw

Aggregate multiple BigWig files

bamnado bigwig-aggregate \
  --bigwigs sample1.bw sample2.bw sample3.bw \
  --method mean \
  --threads 6 \
  -o mean_coverage.bw

Simplify bedGraph file

bamnado collapse-bedgraph \
  --input signal.bedgraph \
  --output signal.collapsed.bedgraph

Normalize between ChIP-seq samples

bamnado bam-normalize \
  --bams chip1.bam chip2.bam chip3.bam \
  --method csaw-background \
  --bin-size 10000 \
  --blacklist blacklist.bed

Apply the reported scale_factor for each sample to bam-coverage -f (or bigwig-aggregate --scale-factors) when generating tracks for that sample.

Between-sample normalization

Comparing ChIP-seq / CUT&Tag / CUT&RUN samples side by side requires removing composition and technical bias, not just sequencing depth. A sample with a stronger pulldown has more of its library consumed by peaks, which deflates its background and makes every other region look artificially low relative to a shallower or weaker-pulldown sample. Simple total-count (CPM) scaling does not correct for this — it's the same problem csaw::normFactors / edgeR::calcNormFactors (TMM) solve in R/Bioconductor.

bamnado bam-normalize bins the genome, counts filtered reads (or fragments) per bin per sample, and reports a per-sample scaling factor plus the underlying bin count matrix for downstream sanity checks (e.g. M-A plots). It reports factors only — it does not generate bigwigs itself.

Method choice

Applying the result

scale_factor is centred on 1 (the geometric mean across samples), so it can be passed directly to bam-coverage -f <factor> or bigwig-aggregate --scale-factors for each corresponding sample.

Use --counts-out counts.tsv to write the underlying bin count matrix (chrom, start, end, one column per sample) for QC, e.g. plotting an M-A plot to confirm the fitted factor sits at the centre of the trimmed M-value cloud.

Spike-in caveat

The spike-in method reads mapped-read counts directly from each BAM's index (no BAM record scan), so those counts are unfiltered by MAPQ, duplicates, or secondary/supplementary status — the same basis as bam-coverage's internal mapped-read count. --exogenous-prefix is required and --bin-size is ignored for this method.

Python API

Installing the Python package also installs the bamnado CLI, including all Rust CLI commands and flags:

pip install bamnado
bamnado bam-coverage --help

BamNado provides Python bindings for high-performance BAM signal generation with flexible read filtering. Install from PyPI:

pip install bamnado
# or
uv pip install bamnado

Quick start

import bamnado
import numpy as np

# Generate coverage from a BAM file
signal = bamnado.get_signal_for_chromosome(
    bam_path="input.bam",
    chromosome_name="chr1",
    bin_size=50,
)
print(f"Mean coverage: {np.mean(signal):.2f}")

ReadFilter class

Customize read filtering with the ReadFilter class. All parameters are optional:

import bamnado

# Create a filter for high-quality, properly-paired reads
strict_filter = bamnado.ReadFilter(
    min_mapq=30,
    proper_pair=True,
    min_length=50,
)

# Apply the filter
signal = bamnado.get_signal_for_chromosome(
    bam_path="input.bam",
    chromosome_name="chr1",
    bin_size=100,
    read_filter=strict_filter,
)

Filter parameters

Usage examples

Basic coverage

import bamnado
import numpy as np

signal = bamnado.get_signal_for_chromosome(
    bam_path="sample.bam",
    chromosome_name="chr1",
    bin_size=50,
    scale_factor=1.0,
    use_fragment=False,
)
print(f"Signal shape: {signal.shape}, type: {signal.dtype}")
print(f"Mean: {np.mean(signal):.2f}, Max: {np.max(signal):.2f}")

Nucleosome-free regions (ATAC-seq)

import bamnado

# Forward-strand reads, 100–200 bp fragments
nfr_filter = bamnado.ReadFilter(
    strand="forward",
    min_fragment_length=100,
    max_fragment_length=200,
    min_mapq=20,
)

nfr_signal = bamnado.get_signal_for_chromosome(
    bam_path="atac.bam",
    chromosome_name="chr1",
    bin_size=10,
    use_fragment=True,
    read_filter=nfr_filter,
)

Barcode-filtered coverage (single-cell)

import bamnado

# Get coverage for specific cell barcodes
cell_barcodes = ["ACGTACGT-1", "TGCATGCA-1", "AAATAAAA-1"]

barcode_filter = bamnado.ReadFilter(
    whitelisted_barcodes=cell_barcodes,
    min_mapq=25,
)

signal = bamnado.get_signal_for_chromosome(
    bam_path="possorted_genome_bam.bam",
    chromosome_name="chr1",
    bin_size=100,
    use_fragment=True,
    read_filter=barcode_filter,
)

Tag-filtered coverage (e.g. MCC viewpoint)

import bamnado

# Get coverage for specific viewpoint
vp_filter = bamnado.ReadFilter(
    filter_tag="VP",
    filter_tag_value="BCL2",
    min_mapq=30,
)

vp_signal = bamnado.get_signal_for_chromosome(
    bam_path="mcc.bam",
    chromosome_name="chr1",
    bin_size=50,
    use_fragment=True,
    read_filter=vp_filter,
)

High-confidence coverage

import bamnado

# High-quality, properly-paired reads
confident_filter = bamnado.ReadFilter(
    min_mapq=30,
    proper_pair=True,
    min_length=50,
    min_fragment_length=100,
    max_fragment_length=500,
)

signal = bamnado.get_signal_for_chromosome(
    bam_path="sample.bam",
    chromosome_name="chr1",
    bin_size=50,
    scale_factor=1e6,  # CPM normalization
    use_fragment=True,
    read_filter=confident_filter,
)

get_signal_for_chromosome parameters

Returns: numpy.ndarray of dtype float32 with length = chromosome size / bin_size

Note: Fragment length filtering (min_fragment_length, max_fragment_length) requires paired-end BAM files and will raise ValueError on single-end data.

Between-sample scaling factors

compute_scale_factors mirrors the bam-normalize CLI command — see Between-sample normalization for the underlying method.

import bamnado

result = bamnado.compute_scale_factors(
    ["chip1.bam", "chip2.bam", "chip3.bam"],
    method="csaw-background",
    bin_size=10000,
)
print(result.sample_names, result.scale_factors)

# Include the bin count matrix for QC (e.g. an M-A plot)
result = bamnado.compute_scale_factors(
    ["chip1.bam", "chip2.bam"],
    method="tmm",
    return_counts=True,
)
counts = result.counts()  # (n_bins, n_samples) uint64 array, or None

compute_scale_factors parameters

Returns: ScaleFactorResult with method, sample_names, library_sizes, norm_factors, scale_factors, reference_sample, n_bins_total, n_bins_used, and (when return_counts=True) counts(), bin_chroms, bin_starts, bin_ends.

Development

cargo build --release
cargo test

License

Apache-2.0 OR MIT