Metadata-Version: 2.5
Name: nanocheck
Version: 0.3.0
Summary: Read-only consistency checks for Oxford Nanopore run directories.
Author: nanocheck contributors
License-Expression: MIT
License-File: LICENSE
Keywords: bam,fastq,nanopore,pod5,quality-control
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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
Requires-Dist: pysam>=0.22
Provides-Extra: all
Requires-Dist: pod5>=0.3.31; extra == 'all'
Provides-Extra: pod5
Requires-Dist: pod5>=0.3.31; extra == 'pod5'
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

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

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

```bash
python -m pip install ".[pod5]"
```

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

```bash
python -m pip install .
```

## Check

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

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

The disk database is deleted when the command finishes.

## Summary

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

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

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

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

nanocheck is independent of Oxford Nanopore Technologie.
