Usage

Usage

nanotimesort -f /path/to/fastq_pass/ -o /path/to/output/ -i 1h -p my_sample

Command-line options

Flag	Required	Description
-f, --fastq	yes	Input folder (searched recursively) or a single FASTQ file. Accepts .fastq, .fq, .fastq.gz and .fq.gz.
-o, --output	yes	Output folder. Created if it does not exist.
-i, --interval	yes	Time interval for the bins, e.g. 1h, 30m or 90s. Fractional values like 0.5h work too. Bins are cumulative.
-m, --max-time	no	Only bin reads acquired up to this elapsed time; later reads are discarded. Same format as --interval. Default: bin the whole run.
-p, --prefix	no	Output file prefix. Default: interval.
-t, --threads	no	Number of FASTQ files to process in parallel. Default: all CPUs.
-c, --compression-level	no	Gzip level for output files, 1 (fastest) to 9 (smallest). Default: 4.
-v, --version	no	Show version and exit.

Output

Files are named {prefix}_0-{end}{unit}_{reads}reads_{bp}bp.fastq.gz, so read and base-pair counts are visible straight from a directory listing:

my_sample_0-1h_125437reads_1103093674bp.fastq.gz
my_sample_0-2h_225891reads_2087456221bp.fastq.gz
my_sample_0-3h_301255reads_2812345678bp.fastq.gz

Bins are cumulative: the 0-2h file also contains the reads of the 0-1h file. The last file holds the complete run. Elapsed time is measured from the earliest read start time found across all input files.

Supported FASTQ headers

Basecaller	Header style	Example time field
Albacore / Guppy	key=value	start_time=2019-07-16T19:51:22Z
MinKNOW live basecalling (incl. built-in Dorado)	key=value	start_time=2025-01-13T10:45:28.681306+00:00
Dorado standalone	SAM tags	st:Z:2023-09-01T11:13:45.731+00:00

Any ISO 8601 / RFC 3339 timestamp flavor is parsed (with Z suffix or numeric offset, with or without fractional seconds). Reads without a recognizable start time are skipped, with a single warning giving the total count.

Basecalled to BAM with Dorado? Convert while keeping the tags:

samtools fastq -T '*' calls.bam | gzip > calls.fastq.gz

Keeping only the start of a run

If you only care about the first part of a run (say, the first two hours), add --max-time so the rest of the run is never compressed:

nanotimesort -f fastq_pass/ -o binned/ -i 2h -m 2h -p my_sample
# -> my_sample_0-2h_...fastq.gz  (a single file, nothing else)

• -i 30m -m 2h gives four cumulative bins covering just the first 2 hours.
• A cutoff smaller than the interval (-i 1h -m 30m) yields a single file named after the cutoff (..._0-30m_...).
• If the cutoff is not a multiple of the interval (-i 30m -m 75m), the last file is named after the actual cutoff (0-30m, 0-60m, 0-75m), so names never claim more time than they contain. The cutoff is inclusive: a read acquired at exactly --max-time is kept.
• This is much faster than binning the whole run: nothing past the cutoff is ever compressed, input files whose reads all start past the cutoff are not read a second time in the binning pass (the initial scan still decompresses every file once to read the timestamps), and the cumulative assembly — whose cost grows quadratically with bin count — only covers the kept window.

Tips

• Parallelism is per file, so -t helps most with the many small files MinKNOW produces (4000 reads per file by default). A single huge FASTQ is processed on one core.
• Use -c 1 when the bins are intermediate files you will delete anyway; use -c 9 for long-term archiving.
• The deprecated nanopore_reads_binner.py wrapper still accepts the same flags, so old pipelines keep working unchanged.