Crate slow5

slow5-rs

A library for interacting with SLOW5/BLOW5 files in rust. Not official.

For more information checkout the main slow5lib repository.

Note: Library design is in flux and care should be taken in upgrading this crate.

Installation

Add the following to your Cargo.toml:

[dependencies]
slow5 = "0.11"

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)

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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
• 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
• 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

• to_picoamps
  Convert raw signal into a picoamps measurement
• to_raw_signal
  Convert picoamps signal into the raw signal