Crate slow5

Source
Expand description

§slow5-rs

License Crates.io docs.rs Rust stable codecov

A library for interacting with SLOW5/BLOW5 files in the Rust programming language.

For more information check out the main slow5lib repository or the paper.

This repository provides two crates:

  • slow5lib-sys: Bindings to the C library using bindgen
  • slow5: Rust API built on-top of slow5lib-sys

The interface for slow5 is largely stable and now updated primarily to follow new versions slow5lib. If there is additional functionality you’d like to see, please file a Github Issue.

§Installation

Add the following to your Cargo.toml:

[dependencies]
slow5 = "0.12"

§Git

If you’d like to download the git version, use the following command to download the repo

git clone --recursive https://github.com/bsaintjo/slow5-rs.git

§Getting started

§Reading signal from SLOW5 file

use slow5::{FileReader, RecordExt};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut slow5 = FileReader::open("examples/example.slow5").unwrap();
    for record in slow5.records() {
        for signal in record?.picoamps_signal_iter() {
            // Do stuff
        }
    }
    Ok(())
}

§Writing a compressed BLOW5 file with attributes

use std::error::Error;
use slow5::{FileWriter, SignalCompression, Record};

fn main() -> Result<(), Box<dyn Error>> {
    let tmp_dir = std::env::temp_dir();
    let output = tmp_dir.join("test.blow5");
    let mut writer = FileWriter::options()
        .signal_compression(SignalCompression::StreamVByte)
        .attr("attribute", "value", 0)
        .create(output)?;
    let rec = Record::builder()
        .read_id("test_id")
        .read_group(0)
        .digitisation(4096.0)
        .offset(4.0)
        .range(12.0)
        .sampling_rate(4000.0)
        .raw_signal(&[0, 1, 2, 3])
        .build()?;
    writer.add_record(&rec)?;
    writer.close();
    Ok(())
}

§More example code

For more example code, see the test code. Several examples from the original library have been ported to rust and can be found in the examples directory.

§Feature flags

  • zstd: Enable zstd-based compression
    • enabled by default
  • zlib-ng: Enable usage of high performance zlib-ng
    • adds cmake dependency
  • serde: Enable serde dependency
    • Mainly for serializing Record into serde-compatible formats

§License

Licensed under either of

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Structs§

AuxEnumLabelIter
Iterator over labels for an auxiliary field enum
AuxNamesIter
Iterator over auxiliary field names of a Header, usually using aux_names_iter
EnumField
Represents the value for an enum field. This struct wraps an index into the labels used for auxiiliary enum field.
FileReader
Read from a SLOW5 file
FileWriter
Write a SLOW5 file
Header
Represents a SLOW5 header
PicoAmpsSignalIter
Iterator over signal in picoamps from Record.
RawSignalIter
Iterator over signal in picoamps from Record.
ReadIdIter
Iterator over all the read IDs in a SLOW5 file
Record
Represents a SLOW5 record.
RecordBuilder
Builder to create a Record, call methods to set parameters and build to convert into a Record.
RecordIter
Iterator over Records from a SLOW5 file.
WriteOptions
Set attributes, auxiliary fields, and record and signal compression.

Enums§

FieldType
Maps between Rust types and SLOW5 C types
LogLevel
Set the log level based on desired verbosity.
RecordCompression
SLOW5 record compression
SignalCompression
SLOW5 signal compression
Slow5Error
Errors from slow5 library

Traits§

AuxField
Helper trait to get auxiliary field values from Record
AuxFieldSetExt
Trait for values that we are allowed to set the values for in Records. Currently only primitive types, strings, and enums are allowed to be used to set auxiliary fields.
HeaderExt
Trait for common Header methods
RecordExt
Trait for accessing Record values.

Functions§

slow5_set_log_level
Sets the global variable for slow5lib to control the libraries logging verbosity. These represent internal logs of the slow5lib and doesn’t interact with logging done by Rust crates.
to_picoamps
Convert raw signal into a picoamps measurement
to_raw_signal
Convert picoamps signal into the raw signal