nanocheck

nanocheck is a read-only inspector for Oxford Nanopore run data. It checks that files are intact and mutually consistent, describes BAM contents, inventories cohorts, and creates verifiable handover manifests.

nanocheck
├── check       integrity and cross-file consistency
├── summary     descriptive QC for one BAM
├── cohort      many BAMs as one table
├── manifest    file inventory and optional checksums
└── verify      verify a saved manifest

nanocheck never changes, indexes, or rewrites sequencing data.

Installation

python -m pip install ".[pod5]"

POD5 support is optional. For BAM/FASTQ-only use:

python -m pip install .

Check

nanocheck check /data/my_run
nanocheck check /data/my_run --json
nanocheck check /data/my_run --strict

check streams BAM, FASTQ, and POD5 files; detects malformed data, mixed run IDs and flow cells, duplicate reads, invalid read-group references, incomplete MM/ML pairs, and sample-sheet problems; and reconciles POD5 read IDs against BAM or FASTQ source IDs. It understands the pi/parent_read_id relationship from read splitting.

Read-ID storage defaults to auto: inputs below 10 GiB use memory and larger inputs use a temporary SQLite database. The exact backend can be selected when needed:

nanocheck check run/ --id-store memory
nanocheck check run/ --id-store disk

The disk database is deleted when the command finishes.

Summary

nanocheck summary sample.bam
nanocheck summary sample.bam --quick
nanocheck summary sample.bam --json
nanocheck summary sample.bam --timeline --timeline-output timeline.tsv

summary reports read and alignment counts, yield, length N50, Q-score, MAPQ, MM/ML presence, index and sort status, the exact reference-dictionary fingerprint, and ONT run, flow-cell, sample, barcode, basecaller, basecalling model, and modified-base model metadata. When st is available it also reports the first and last reads, run duration, and per-minute yield.

Full mode is the default. Quick mode reads at most the first 100,000 records and checks the BAM header and EOF marker. Sampled output is marked as incomplete.

Reference labels are conservative hints based on canonical chromosome lengths: GRCh37, GRCh38, T2T-CHM13v2.0, or unknown/custom. Cohort comparisons use the complete ordered @SQ name/length dictionary, not the hint or filename.

Cohort

nanocheck cohort /data/brain_tumors/*.bam
nanocheck cohort /data/bams --recursive --output cohort.tsv
nanocheck cohort /data/bams --recursive --csv
nanocheck cohort /data/bams --recursive --jsonl > cohort.jsonl

TSV, CSV, JSON, and JSONL exports include paths, file sizes, ONT metadata, reference, alignment counts, yield and length statistics, mapping metrics, MM/ML fractions, index status, errors, and warnings. Terminal output highlights mixed reference dictionaries and mixed basecalling configurations. Use --quick to sample each BAM.

Manifest and verification

nanocheck manifest /data/project > manifest.tsv
nanocheck manifest /data/project --checksum sha256 -o manifest.json
nanocheck verify manifest.json

Manifests recursively inventory all files. BAM, FASTQ, and POD5 entries also include available read and ONT metadata. JSON or TSV is selected from the output filename or explicitly with --json/--tsv. Verification always checks file sizes and checks hashes when the manifest contains them.

Exit status

Commands return 1 for errors. check --strict also returns 1 for warnings. cohort returns 1 for unreadable BAMs, an empty selection, or mixed reference dictionaries.

Development

python -m pip install -e ".[test,pod5]"
pytest

nanocheck is independent of Oxford Nanopore Technologie.