escapepod

Warning

escapepod is alpha quality and under active development. APIs, CLI flags, and output formats may change without notice, and bugs are expected. Verify results against the official ONT pod5 tools before relying on it for anything important.

A Rust library and CLI for reading and writing Oxford Nanopore POD5 files.

Highlights

• Fast - Up to 9x faster than Python pod5 tools on large-file operations
• Memory efficient - Memory-mapped I/O for large files
• Full featured - View, inspect, merge, filter, subset
• BAM integration - Filter reads by alignment status
• Barcode demultiplexing - escpod demux runs DTW-SVM, GBM, or CTC-CRF classification end to end, in the default build
• .p5s sidecar - Barcode assignments, experimental designs, and a read index live in a small Arrow file beside the POD5 — raw sequencer output is never modified, and per-barcode subsets are materialized on demand instead of stored
• Crash-safe writes - Output is staged and renamed into place, so an interrupted run never leaves a corrupt archive or damages an existing one

Some commands — repack, resquiggle, index, annotate — are experimental and live behind the experimental Cargo feature; GPU acceleration for demux is a single opt-in flag (--features gpu). See the docs for status, build instructions, and the details behind the highlights above.

Performance

Numbers are for the I/O-bound operations where runtime is large enough to matter; sub-second commands (inspect, view) are omitted. Measured with benchmarks/benchmark.sh (hyperfine, 3 runs) versus the official Python pod5 (v0.3.36) on ~500k RNA004 reads (two ~250k-read files).

Command	escapepod	pod5	Speedup
filter	361 ms	3.4 s	9.3x
subset	1.4 s	5.1 s	3.6x
merge	2.0 s	6.7 s	3.3x

Install

CLI (escpod)

The escpod binary lives in the escapepod-cli crate.

Default build (stable commands only):

cargo install --git https://github.com/rnabioco/escapepod-rs escapepod-cli

Opt into experimental commands:

# repack, resquiggle, index, annotate
cargo install --git https://github.com/rnabioco/escapepod-rs escapepod-cli --features experimental

Python library

The escapepod Python package — a pod5-compatible API — is published on PyPI:

uv pip install escapepod

Prebuilt wheels cover CPython 3.9+ (abi3) on Linux (x86_64/aarch64, manylinux + musllinux) and macOS (x86_64/arm64). See the Python API docs for usage and building from source.

License

MIT.

Acknowledgments

escapepod-rs stands on the shoulders of giants. The format, algorithms, and prior tools that made this project possible:

POD5 format and Oxford Nanopore tooling

• POD5 file format — Oxford Nanopore Technologies. escapepod-rs is a pure-Rust reader/writer for the POD5 specification. The official C++/Python reference is licensed under MPL-2.0; we do not redistribute any of its code.
• Tombo — Oxford Nanopore Technologies. The t-test changepoint segmentation in escapepod-signal::segmentation::ttest is based on the Tombo algorithm.
• dorado and remora — used as references for signal handling conventions.

Barcode demultiplexing — KleistLab (van der Toorn / von Kleist labs)

The escpod demux workflow is a pure-Rust reimplementation of algorithms from the KleistLab:

• WarpDemuX — DTW+SVM barcode classifier. We reimplement the model JSON loader, DTW distance, RBF kernel, OvO dual coefficients, Platt scaling, and probability coupling to be byte-for-byte compatible with exported WarpDemuX models.

• ADAPTed (Adapter and poly(A) Detection And Profiling Tool) by Wiep K. van der Toorn et al. The LLR boundary detector in escapepod-signal::segmentation::llr is adapted from ADAPTed, and escapepod-demux::adapter_cnn is a runtime port of ADAPTed's BoundariesCNN through tract-onnx.

  Note on CNN weights: the cnn-detect code is in the default build, but no weights are bundled — the detector is architecture-agnostic and takes any ONNX graph on the [B,1,L] -> [B,2,L] contract at runtime. escapepod-rs points users at escapepod-models' adapter_rna004 TCN (CC BY 4.0). ADAPTed's own trained weights are licensed CC BY-NC 4.0; users who prefer those must export their own ONNX file from a local ADAPTed install (see scripts/export_adapter_cnn_to_onnx.py) and accept ADAPTed's license terms separately.

Signal-to-base resquiggle

• fishnet by Brickner et al. The banded DP refinement and signal rescaling in escapepod-signal::resquiggle is inspired by fishnet.
• Remora — Oxford Nanopore Technologies. Referenced for signal-to-sequence anchoring conventions.
• nanopolish by Jared Simpson et al. Referenced for its event-alignment approach to signal-to-base assignment.

Signal compression

• StreamVByte by Daniel Lemire. The SVB16 variant used by POD5's VBZ codec is derived from StreamVByte's design; our Rust scalar + SSSE3/AVX2 implementations are clean-room.
• zstd — the second stage of the VBZ pipeline.

Citation

If you use escapepod-rs in research, please also cite the upstream tools whose algorithms it implements (WarpDemuX, ADAPTed, fishnet, POD5).

If we've missed an acknowledgment, please open an issue.