Skip to content

Library Overview

The escapepod library provides Rust APIs for reading and writing POD5 files.

Crate layout

The library is split across two layers plus two analysis crates on top:

Crate Purpose
escapepod-pod5 POD5 format I/O — reader, writer, VBZ compression, footer parsing, block-level merge/filter/subset
escapepod-signal Signal-processing algorithms (DTW, resquiggle, segmentation, k-mer primitives) layered on top of pod5. Re-exports the full pod5 surface
escapepod-demux WarpDemuX-compatible barcode demultiplexing plus CTC-CRF basecalling. Separate crate; in the default CLI build, or opt in for library use via --features demux
escapepod-classify Read-level classification against model bundles (the tRNA charging classifier). In the default CLI build; --features classify for library use

Most users should depend on escapepod-signal — depending on it gives you both the format I/O and the signal algorithms via a single dependency. Depend directly on escapepod-pod5 only if you want format I/O without pulling in signal-processing code.

Features

  • Read POD5 files - Memory-mapped, efficient reading of reads and signal data
  • Write POD5 files - Create new POD5 files with automatic compression
  • Signal compression - VBZ codec (SVB16 + ZSTD) for signal data
  • Full metadata support - Read/write run info, calibration, and pore data
  • Sidecar annotations - .p5s read index plus per-read annotations (demux barcodes, experimental designs), without touching the POD5

Quick Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
use escapepod_signal::{Reader, Writer, WriterOptions, ReadData, RunInfoData};

// Read a POD5 file
let reader = Reader::open("input.pod5")?;
println!("File contains {} reads", reader.read_count());

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

// Write a new POD5 file
let mut writer = Writer::create("output.pod5", WriterOptions::default())?;
writer.add_run_info(run_info)?;
writer.add_read(read_data, &signal)?;
writer.finish()?;

Modules

Module Description
Reading Reading POD5 files
Writing Creating POD5 files
Types Data structures and types

Error Handling

All operations return Result<T, escapepod_signal::Error>. The error type provides detailed information about what went wrong:

1
2
3
4
5
6
7
8
use escapepod_signal::{Reader, Error};

match Reader::open("file.pod5") {
    Ok(reader) => { /* use reader */ }
    Err(Error::Io(e)) => eprintln!("I/O error: {}", e),
    Err(Error::InvalidSignature) => eprintln!("Not a valid POD5 file"),
    Err(e) => eprintln!("Error: {}", e),
}