NanoRunner

NanoRunner is a nanopore sequencing run simulator. It delivers FASTQ files into a target directory with controlled timing so that watch-directory analysis pipelines can be exercised without an active sequencer.

Two run modes:

• Replay -- transfer existing FASTQ files into the target with configurable timing. Accepts a single FASTQ file, a flat directory of FASTQs, or barcoded subdirectories. Can rechunk a large FASTQ into many small files and reshape the output layout independently of the input (any of the three shapes can become any of the three).
• Generate -- produce simulated reads from genome FASTAs, species names, NCBI taxonomy IDs, explicit NCBI assembly accessions (e.g. GCA_000005845.2), or built-in mock community presets, and deliver them with the same timing models.

Output is compatible with watch-directory pipelines such as Nanometa Live and nanometanf.

Install

conda create -n nanorunner python=3.10
conda activate nanorunner
pip install git+https://github.com/FOI-Bioinformatics/nanorunner.git@v3.1.0
nanorunner --help

First run

# Replay an existing run into a watch directory at 5 s intervals
nanorunner replay --source /data/run01 --target /watch/output --interval 5

# Generate 1000 simulated reads from one genome
nanorunner generate --genomes genome.fa --target /watch/output --interval 5

Documentation

See docs/ for the full documentation:

• Getting started
• Replay guide -- includes the 3x3 input/output reshape matrix.
• Generate guide
• Timing models
• Pipeline integration
• CLI reference
• Configuration reference
• Troubleshooting
• Examples -- runnable scripts
• CLAUDE.md -- developer guide

For an end-to-end demo driving Nanometa Live with simulated reads, see the Nanometa Live integration walkthrough.

Requirements

• Python 3.9 or later
• POSIX-compliant operating system (Linux, macOS)
• Optional: psutil for resource monitoring; badread or nanosim for higher-fidelity read simulation; ncbi-datasets-cli for --species / --mock workflows

Run nanorunner check-deps for a current dependency status report.

Citation

If you use NanoRunner in research, please cite:

NanoRunner: a nanopore sequencing run simulator for testing watch-directory analysis pipelines. FOI Bioinformatics, Swedish Defence Research Agency. https://github.com/FOI-Bioinformatics/nanorunner

License

MIT License. See LICENSE for details.

Developed by FOI Bioinformatics at the Swedish Defence Research Agency.