Metadata-Version: 2.4
Name: bam-check
Version: 1.0.2
Summary: Validate agreement between BAM mapped-read metrics reported by samtools flagstat and samtools idxstats.
Author: Samson Ayodeji Olofinsae
License-Expression: MIT
Project-URL: Homepage, https://github.com/samson-olofinsae/bam-check
Project-URL: Repository, https://github.com/samson-olofinsae/bam-check
Project-URL: Issues, https://github.com/samson-olofinsae/bam-check/issues
Keywords: bioinformatics,genomics,BAM,samtools,quality control,sequencing metrics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# bam-check

[![DOI](https://zenodo.org/badge/1298392087.svg)](https://doi.org/10.5281/zenodo.21459973)

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

```bash
python --version
samtools --version
git --version
```

---

### Clone the repository

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

---

### Create and activate a virtual environment

Linux/macOS:

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

Windows (PowerShell):

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

---

### Install bam-check

#### Standard installation

Install **bam-check**:

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

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

---

### Verify the installation

Check that the installation was successful:

```bash
bam-check --version
```

Example output:

```text
bam-check 1.0.2
```

Display the command-line help:

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

```bash
bam-check sample.bam
```

Example output:

```text
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:

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

```bash
bam-check sample.bam --save-raw
```

Raw outputs are written to:

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

---

### Produce verbose execution logs

For detailed execution information:

```bash
bam-check sample.bam --verbose
```

Verbose mode displays:

- detected `samtools` executable;
- `samtools` version;
- executed commands;
- processing summary.

---

### Specify a custom output directory

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

```bash
bam-check sample.bam --overwrite
```

---

### Suppress summary output

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

```bash
bam-check sample.bam --quiet
```

Only essential messages and errors are displayed.

---

### Generate specific report formats

Generate only TSV output:

```bash
bam-check sample.bam --format tsv
```

Generate only JSON output:

```bash
bam-check sample.bam --format json
```

Generate both (default):

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

```text
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:

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

```text
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:

```text
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`](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.
