binseq 0.11.0

A high efficiency binary format for sequencing data
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(docsrs, doc(auto_cfg))]
#![doc = include_str!("../README.md")]
//!
//! # Library
//!
//! The `binseq` library provides efficient APIs for working with the [BINSEQ](https://www.biorxiv.org/content/10.1101/2025.04.08.647863v2) 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(())
//! }
//! ```

#![allow(clippy::module_inception)]
#![cfg_attr(test, allow(clippy::assert_is_empty))]

/// CBQ - columnar variable-length records, optional quality scores and headers
pub mod cbq;

/// BQ - fixed-length records, no quality scores
pub mod bq;

/// VBQ - variable-length records, optional quality scores, compressed blocks
pub mod vbq;

/// Shared nucleotide encoder for BQ/VBQ writers
mod encoder;

/// Error definitions
pub mod error;

/// Parallel processing
mod parallel;

/// Invalid nucleotide policy
mod policy;

/// Record types and traits shared between BINSEQ variants
mod record;

/// Commonly used types and traits
pub mod prelude;

/// Write operations generic over the BINSEQ variant
pub mod write;

/// Utilities for working with BINSEQ files
pub mod utils;

pub use error::{Error, IntoBinseqError, Result};
pub use parallel::{BinseqReader, ParallelProcessor, ParallelReader};
pub use policy::Policy;
pub use record::{BinseqRecord, SequencingRecord, SequencingRecordBuilder};
pub use write::{BinseqWriter, BinseqWriterBuilder};

/// Re-export `bitnuc::BitSize`
pub use bitnuc_deprec::BitSize;

/// Default quality score for BINSEQ readers without quality scores
pub(crate) const DEFAULT_QUALITY_SCORE: u8 = b'?';