Crate binseq 

BINSEQ

Overview

BINSEQ is a binary file format family for efficient storage and processing of DNA sequences. It uses two-bit encoding for nucleotides and is optimized for high-performance parallel processing.

The recommended variant is CBQ (*.cbq): a columnar, block-compressed format for variable-length records with optional quality scores and headers. It is lossless by default (native N support), compresses well, and decodes fast. For details on its structure see the documentation.

Two earlier variants remain supported:

• BQ (*.bq): fixed-length records without quality scores. Minimal and fast for uniform reads.
• VBQ (*.vbq): variable-length records with optional quality scores and headers. Superseded by CBQ, which improves on its compression and decoding speed; new projects should use CBQ.

All variants support both single and paired sequences.

Getting Started

This is a library for reading and writing BINSEQ files; for a command-line interface see bqtools.

To get started please refer to our documentation. For example programs which make use of the library check out our examples directory.

For more information about the BINSEQ file family, please refer to our preprint.

Development

Commits are checked with prek, which runs cargo fmt --check and cargo clippy --all-targets --all-features -- -D warnings. Register the hooks once per clone:

uv tool install prek && prek install

Library

The binseq library provides efficient APIs for working with the BINSEQ file format family:

• cbq — the recommended variant: columnar, block-compressed, lossless by default
• bq and vbq — earlier variants, still fully supported
• BinseqRecord, BinseqReader, and BinseqWriter — variant-agnostic record, reader, and writer abstractions
• ParallelProcessor — parallel processing of records with arbitrary per-record logic
• Policy — configurable handling of invalid nucleotides when encoding BQ/VBQ (CBQ stores N natively)

Example: Parallel Processing

use binseq::Result;
use binseq::prelude::*;

#[derive(Clone, Default)]
pub struct Processor {
    // per-thread state
}

impl ParallelProcessor for Processor {
    fn process_record<B: BinseqRecord>(&mut self, record: B) -> Result<()> {
        // per-record logic
        Ok(())
    }

    fn on_batch_complete(&mut self) -> Result<()> {
        // per-batch logic (e.g. flush to a shared writer)
        Ok(())
    }
}

fn main() -> Result<()> {
    // any BINSEQ variant (*.cbq, *.bq, *.vbq); format is sniffed from content
    let path = "./data/subset.cbq";

    let reader = BinseqReader::new(path)?;
    let processor = Processor::default();

    // process records in parallel with 8 threads
    reader.process_parallel(processor, 8)?;
    Ok(())
}

Re-exports

pub use error::Error;

pub use error::IntoBinseqError;

pub use error::Result;

pub use write::BinseqWriter;

pub use write::BinseqWriterBuilder;

Modules

bq

BQ - fixed-length records, no quality scores

cbq

CBQ - columnar variable-length records, optional quality scores and headers

error

Error definitions

prelude

Commonly used types and traits

utils

Utilities for working with BINSEQ files Utility modules for working with BINSEQ files

vbq

VBQ - variable-length records, optional quality scores, compressed blocks

write

Write operations generic over the BINSEQ variant Unified writer interface for BINSEQ formats

Structs

SequencingRecord

A zero-copy (borrowed) record used to write sequences to any BINSEQ format.

SequencingRecordBuilder

Builder for a SequencingRecord

Enums

BinseqReader

An enum abstraction for BINSEQ readers that can process records in parallel

BitSize

Re-export bitnuc::BitSize

Policy

Policy for handling invalid nucleotides (anything other than A, C, G, T) during encoding

Traits

BinseqRecord

Record trait shared between BINSEQ variants.

ParallelProcessor

Trait for types that can process records in parallel.

ParallelReader

Trait for BINSEQ readers that can process records in parallel