API Reference¶

Full API documentation is generated from source code using cargo doc.

Generating Documentation¶

cd escapepod-rs
cargo doc --open --no-deps

This opens the documentation in your browser.

Crate Structure¶

The workspace is split into six crates:

escapepod-pod5¶

Format I/O.

Main types: Reader, Writer, WriterOptions, ReadData, RunInfoData, EndReason, Error.

Modules: reader, writer, compression (VBZ / SVB16 / ZSTD), footer (FlatBuffer), schema (Arrow schemas), types, merge, sidecar (the .p5s companion file), operations::{filter, repack, subset, annotate} (including read_annotation / write_annotation / read_design).

escapepod-signal¶

Signal-processing algorithms, layered on top of escapepod-pod5 (which it re-exports).

Modules: dtw (distance, fingerprint, kernel, optional cuda), segmentation (LLR, t-test, normalize), resquiggle (banded DP), seq_encoding (signal-level k-mer encoding and the k-mer context window), mapping (move-table and CIGAR coordinate mapping), stats (span statistics), features.

escapepod-demux¶

Barcode demultiplexing. Separate crate; included in the default CLI build (it adds no third-party dependencies), and available to library consumers via --features demux.

Modules: model (JSON loaders), classify (per-read and batched GPU), svm (RBF kernel + Platt scaling), probability, crf (CTC-CRF lattice decode; encoder/barcode behind crf-decode), train (feature train), adapter_cnn (feature cnn-detect).

escapepod-classify¶

Read-level classification against model bundles. Included in the default CLI build (it adds no third-party crates beyond the CLI graph), and available to library consumers via --features classify.

The bundle carries the whole feature recipe — feature order and offsets, the k-mer table pinned by sha256, the operating point — under a closed metadata schema, so a rule this runtime does not implement is refused at load rather than silently dropped. Every definition of the model's input lives here rather than in a caller, so a corpus builder and the inference path cannot diverge.

Modules: bundle (loading + the closed metadata schema), recipe (the feature space as a borrowed view), features, window (raw-signal windowing, junction anchoring, common-arm mask), anchor / geometry (CIGAR and move-table coordinate mapping), pipeline, bam_tags, fnn (the ONNX feature-network scorer, feature fnn-onnx).

Main types: ChargingBundle, ChargingScorer (gbm | feature_model), FeatureRecipe, FeatureNet.

escapepod-cli¶

The escpod binary, built by the default cli feature — so cargo install --git https://github.com/rnabioco/escapepod-rs ships the tool. The same crate doubles as an umbrella library: default-features = false plus pod5 / signal / demux re-exports the corresponding layer (e.g. escapepod_cli::signal) without the CLI's dependency tree. Commands built with cli: summary, view, inspect, merge, filter, bam-filter, subset, index, the demux tree, and classify. repack, resquiggle, and annotate live behind the experimental feature — see below.

Quick Reference¶

Opening Files¶

1
2
3

use escapepod_signal::Reader;

let reader = Reader::open("file.pod5")?;

Creating Files¶

1
2
3

use escapepod_signal::{Writer, WriterOptions};

let writer = Writer::create("output.pod5", WriterOptions::default())?;

Read Iteration¶

1
2
3

for read in reader.reads()? {
    println!("{}: {} samples", read.read_id, read.num_samples);
}

Signal Access¶

1

let signal: Vec<i16> = reader.get_signal(&read)?;

Run Info¶

1
2

let run_info = reader.get_run_info(read.run_info_index)?;
println!("Sample rate: {} Hz", run_info.sample_rate);

Writing Reads¶

1
2
3

writer.add_run_info(run_info)?;
writer.add_read(read_data, &signal)?;
writer.finish()?;

Error Handling¶

1
2
3
4
5
6
7
8

use escapepod_signal::Error;

match result {
    Ok(value) => { /* success */ }
    Err(Error::Io(e)) => eprintln!("I/O: {}", e),
    Err(Error::InvalidSignature) => eprintln!("Invalid file"),
    Err(e) => eprintln!("Error: {}", e),
}

Feature Flags¶

escapepod-cli¶

escapepod-demux¶

escapepod-classify¶

A bundle holding a feature_model is unusable without fnn-onnx, and that is the arm escapepod-models ships, so the CLI turns it on unconditionally: tract is already in the binary via cnn-detect, making it free there.

The CLI features forward to the matching demux features, so building the CLI with --features gpu transitively enables demux's gpu feature.

escapepod-signal's own gpu feature is narrower on purpose: it is the cudarc DTW kernel and nothing else, with no onnxruntime in its graph. That crate has no git dependency blocking publication, which is why it keeps a separate flag while escapepod-demux does not.

Dependencies¶

escapepod-pod5¶

escapepod-signal¶

escapepod-demux¶

escapepod-classify¶

escapepod-cli (cli feature)¶

Minimum Supported Rust Version¶

Rust 1.95 or later is required (tracked in [workspace.package].rust-version).