bam-check

bam-check is an open-source Python command-line application for validating agreement between BAM-derived mapped-read metrics reported by samtools flagstat and samtools idxstats.

bam-check is archived on Zenodo with a permanent DOI, making each software release fully citable and reproducible for scientific research.

The software executes both commands on one or more BAM files, extracts mapped-read counts, compares the reported values, and produces structured validation reports in TSV and JSON formats. Each analysis is classified as PASS, WARN, or FAIL according to a configurable tolerance, providing a transparent and reproducible assessment of metric agreement.

The development of bam-check was motivated by the need for an automated, reproducible method of verifying mapped-read consistency in high-throughput sequencing workflows. The software accompanies a computational benchmarking study evaluating agreement between samtools flagstat and samtools idxstats across controlled sequencing-depth experiments using publicly available cancer sequencing datasets.

Designed for bioinformatics researchers, research software engineers, sequencing facilities, and computational genomics laboratories, bam-check aims to simplify routine validation of mapped-read metrics while promoting reproducibility, transparency, and confidence in downstream analyses.

Key Features

• Automated metric validation – Executes both samtools flagstat and samtools idxstats and compares their mapped-read counts automatically.

• Batch processing – Analyse one or many BAM files in a single command.

• Structured agreement assessment – Calculates absolute difference, relative difference, and agreement percentage between the two mapped-read metrics.

• PASS/WARN/FAIL classification – Assigns an interpretable validation status based on a configurable tolerance threshold.

• Multiple report formats – Produces machine-readable JSON reports and tab-delimited (TSV) summary tables suitable for downstream analysis.

• Raw output preservation – Optionally saves the original samtools flagstat and samtools idxstats outputs for auditing and reproducibility.

• Command-line interface – Provides a simple, consistent interface for interactive use and integration into automated bioinformatics workflows.

• Reproducible workflow – Generates consistent, structured outputs suitable for research, quality assurance, and benchmarking studies.

• Open source – Developed as an open-source Python package to encourage transparency, reproducibility, and community contribution.

• Scientifically validated – The software implements a workflow evaluated through controlled benchmarking on publicly available cancer sequencing BAM datasets.

Installation

Requirements

Supported platforms

bam-check is developed and validated on Linux and has also been successfully tested under Windows Subsystem for Linux (WSL). Native Windows environments may require additional configuration of samtools.

Before installing bam-check, ensure the following software is available:

• Python 3.10 or later
• samtools (version 1.19 or later recommended)
• Git (for cloning the repository)

You can verify your installations with:

python --version
samtools --version
git --version

---

Clone the repository

git clone https://github.com/samson-olofinsae/bam-check.git
cd bam-check

---

Create and activate a virtual environment

Linux/macOS:

python -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

python -m venv .venv
.venv\Scripts\Activate.ps1

---

Install bam-check

Standard installation

Install bam-check:

python -m pip install -e .

Developer installation

If you intend to contribute to the project or run the automated test suite, install the optional development dependencies:

python -m pip install -e ".[dev]"

---

Verify the installation

Check that the installation was successful:

bam-check --version

Example output:

bam-check 1.0.2

Display the command-line help:

bam-check --help

If both commands execute successfully, bam-check is ready for use.

Quick Start

Analyse a single BAM file

Run bam-check on a single BAM file:

bam-check sample.bam

Example output:

bam-check 1.0.2

BAM metric comparison and reporting completed successfully.
Input files validated: 1
BAM files analysed: 1
Output directory: bam_check_results
Tolerance: 0.0
Output format: both

Mapped-read comparison results:

Sample: sample
  flagstat mapped reads: 97633936
  idxstats mapped reads: 97633936
  absolute difference: 0
  relative difference: 0.000000%
  agreement: 100.000000%
  status: PASS
  reason: Mapped-read counts agree exactly.

Batch summary:
  PASS: 1
  WARN: 0
  FAIL: 0

Reports written:
  bam_check_results/bam_check_summary.tsv
  bam_check_results/bam_check_report.json

---

Analyse multiple BAM files

Multiple BAM files can be analysed in a single command:

bam-check sample1.bam sample2.bam sample3.bam

A separate result is produced for each BAM file together with an overall batch summary.

---

Save raw samtools outputs

To preserve the original outputs generated by samtools flagstat and samtools idxstats:

bam-check sample.bam --save-raw

Raw outputs are written to:

bam_check_results/
└── raw/
    ├── sample.flagstat.txt
    └── sample.idxstats.txt

---

Produce verbose execution logs

For detailed execution information:

bam-check sample.bam --verbose

Verbose mode displays:

• detected samtools executable;
• samtools version;
• executed commands;
• processing summary.

---

Specify a custom output directory

bam-check sample.bam \
    --outdir my_results

---

Overwrite existing reports

By default, bam-check prevents existing report files from being overwritten.

To replace previously generated reports in the output directory:

bam-check sample.bam --overwrite

---

Suppress summary output

For quieter execution (for example, in automated workflows):

bam-check sample.bam --quiet

Only essential messages and errors are displayed.

---

Generate specific report formats

Generate only TSV output:

bam-check sample.bam --format tsv

Generate only JSON output:

bam-check sample.bam --format json

Generate both (default):

bam-check sample.bam --format both

Understanding the Output

For each analysed BAM file, bam-check compares the mapped-read counts reported by samtools flagstat and samtools idxstats and calculates:

Metric	Description
Flagstat mapped reads	Number of mapped reads reported by samtools flagstat.
Idxstats mapped reads	Number of mapped reads reported by samtools idxstats.
Absolute difference	The absolute numerical difference between the two mapped-read counts.
Relative difference	The absolute difference divided by the larger mapped-read count.
Agreement percentage	Percentage agreement between the two reported mapped-read counts.
Status	Overall validation result: PASS, WARN, or FAIL.
Reason	Human-readable explanation of the assigned status.

---

Validation Status

The validation statuses reported by bam-check describe the level of agreement between the mapped-read counts reported by samtools flagstat and samtools idxstats. They do not assess the biological quality of a BAM file or the overall quality of the sequencing experiment.

PASS

A PASS indicates exact agreement between the mapped-read counts reported by samtools flagstat and samtools idxstats.

Typical output:

absolute difference: 0
agreement: 100.000000%
status: PASS

---

WARN

A WARN indicates that the mapped-read counts differ, but the discrepancy is within the user-specified tolerance.

For example:

bam-check sample.bam --tolerance 0.01

• --tolerance 0.00 requires exact agreement.
• --tolerance 0.01 allows differences up to 1% of the larger mapped-read count.
• --tolerance 0.05 allows differences up to 5%.

A discrepancy that remains within the configured tolerance produces a WARN result rather than a FAIL.

---

FAIL

A FAIL indicates that the discrepancy exceeds the configured tolerance.

This suggests that the reported mapped-read counts should be investigated before relying on downstream analyses.

---

Output Files

By default, bam-check generates:

bam_check_results/
├── bam_check_summary.tsv
└── bam_check_report.json

If --save-raw is specified, the original outputs from samtools flagstat and samtools idxstats are also preserved:

bam_check_results/
├── bam_check_summary.tsv
├── bam_check_report.json
└── raw/
    ├── sample.flagstat.txt
    └── sample.idxstats.txt

Documentation

Additional documentation is available in the docs/ directory.

Document	Description
user_guide.md	Step-by-step guide to installing and using bam-check.
cli_reference.md	Complete reference for all command-line options and arguments.
output_formats.md	Description of the generated TSV and JSON report formats.
software_requirements.md	Software dependencies, supported environments, and installation requirements.
real_world_validation.md	Summary of validation experiments performed using real cancer sequencing BAM files.
release_candidate_audit.md	Formal assessment of the software immediately before the Version 1.0.0 release.

The project documentation is intended to complement the README by providing more detailed technical information for users and contributors.

Citation

If bam-check contributes to your research, please cite the software using its Zenodo record.

Olofinsae SA. bam-check: Validation of Agreement Between BAM-Derived Mapped-Read Metrics. Version 1.0.1. Zenodo; 2026. https://doi.org/10.5281/zenodo.21459974

Citation metadata is also provided in the repository's CITATION.cff file, which is recognised automatically by GitHub and many reference management tools.

The accompanying computational benchmarking manuscript describing the scientific validation of bam-check is currently in preparation and will be linked here following publication.

Licence

bam-check is released under the MIT License.

You are free to use, modify, and distribute the software in accordance with the terms of the licence.

See the LICENSE file for the full licence text.

Author

bam-check was developed by Samson A. Olofinsae, a computational genomics researcher and research software engineer with experience in cancer genomics, bioinformatics pipeline development, and clinical bioinformatics.

The software was developed as part of a broader programme of work focused on improving the reproducibility, transparency, and reliability of computational methods used in high-throughput sequencing analysis.

Development has followed a structured software engineering approach emphasising modular architecture, automated testing, comprehensive documentation, and reproducible scientific workflows.

Why bam-check?

Modern genomics research depends heavily on computational tools. As sequencing datasets continue to increase in size and complexity, confidence in computational results becomes just as important as generating those results.

Although samtools flagstat and samtools idxstats are widely used to report mapped-read metrics from BAM files, researchers may wish to verify that both commands produce consistent mapped-read counts before using those values in downstream analyses, quality assessment, benchmarking studies, or reproducible research workflows.

bam-check was developed to make that verification straightforward, transparent, and reproducible. Rather than replacing existing tools, it complements them by providing an automated framework for comparing their mapped-read metrics, documenting the results, and preserving the evidence supporting each comparison.

The software reflects a broader commitment to reproducible computational genomics, where scientific confidence is strengthened not only through well-designed experiments, but also through careful validation of the computational methods used to analyse sequencing data.

Roadmap

The current release of bam-check focuses on validating agreement between mapped-read metrics reported by samtools flagstat and samtools idxstats.

Future development may include:

• support for additional BAM-derived metrics;
• expanded reporting and visualisation;
• integration with workflow management systems such as Nextflow;
• distribution through PyPI, conda-forge, and Bioconda;
• continued improvements driven by community feedback and reproducible genomics research.