Crate nafcodec

source ·
Expand description

§📦🧬 nafcodec Stars

Rust coder/decoder for Nucleotide Archive Format (NAF) files.

Actions Codecov License Source Mirror Crate Documentation Changelog GitHub issues

§🗺️ Overview

Nucleotide Archive Format is a file format proposed in Kryukov et al.[1] in 2019 for storing compressed nucleotide or protein sequences combining 4-bit encoding and Zstandard compression. NAF files can be compressed and decompressed using the original C implementation.

This crate provides a Rust implementation of a NAF decoder, from scratch, using nom for parsing the binary format, and zstd for handling Zstandard decompression. It provides a complete API that allows iterating over the contents of a NAF file.

This is the Rust version, there is a Python package available as well.

§📋 Features

  • streaming decoder: The decoder is implemented using different readers each accessing a region of the compressed file, allowing to stream records without having to decode full blocks.
  • optional decoding: Allow the decoder to skip the decoding of certains fields, such as ignoring quality strings when they are not needed.
  • flexible encoder: The encoder is implemented using an abstract storage interface for temporary data, which allows to keep sequence in memory or inside a temporary folder.

§🔌 Usage

Use a Decoder to iterate over the contents of a Nucleotide Archive Format, reading from any BufRead + Seek implementor:

let mut decoder = nafcodec::Decoder::from_path("../data/LuxC.naf")
    .expect("failed to open nucleotide archive");

for result in decoder {
    let record = result.unwrap();
    // .. do something with the record .. //
}

All fields of the obtained Record are optional, and actually depend on the kind of data that was compressed. The decoder can be configured through a DecoderBuilder to ignore some fields to make decompression faster, even if they are present in the source archive:

let mut decoder = nafcodec::DecoderBuilder::new()
    .quality(false)
    .with_path("../data/phix.naf")
    .expect("failed to open nucleotide archive");

// the archive contains quality strings...
assert!(decoder.header().flags().test(nafcodec::Flag::Quality));

// ... but we configured the decoder to ignore them
for result in decoder {
    let record = result.unwrap();
    assert!(record.quality.is_none())
}

§💭 Feedback

§⚠️ Issue Tracker

Found a bug ? Have an enhancement request ? Head over to the GitHub issue tracker if you need to report or ask something. If you are filing in on a bug, please include as much information as you can about the issue, and try to recreate the same bug in a simple, easily reproducible situation.

§📋 Changelog

This project adheres to Semantic Versioning and provides a changelog in the Keep a Changelog format.

§⚖️ License

This library is provided under the open-source MIT license. The NAF specification is in the public domain.

This project is in no way not affiliated, sponsored, or otherwise endorsed by the original NAF authors. It was developed by Martin Larralde during his PhD project at the European Molecular Biology Laboratory in the Zeller team.

§📚 References

  • [1] Kirill Kryukov, Mahoko Takahashi Ueda, So Nakagawa, Tadashi Imanishi. “Nucleotide Archival Format (NAF) enables efficient lossless reference-free compression of DNA sequences”. Bioinformatics, Volume 35, Issue 19, October 2019, Pages 3826–3828. doi:10.1093/bioinformatics/btz144

Modules§

  • Common error type for this crate.

Structs§

  • A decoder for Nucleotide Archive Format files.
  • A builder to configure and initialize a Decoder.
  • An encoder for Nucleotide Archive Format files.
  • A builder to configure and initialize an Encoder.
  • The flags for optional content blocks inside a NAF archive.
  • The header section of a Nucleotide Archive Format file.
  • A marker type for in-memory storage.
  • A single sequence record from a Nucleotide Archive Format file.

Enums§

  • A single flag inside header flags.
  • The supported format versions inside NAF archives.
  • The type of sequence stored in a Nucleotide Archive Format file.

Traits§

  • An abstract interface for temporary I/O storage.