rsomics-pileup

Validated, low-allocation pileup columns shared by alignment-oriented rsomics products.

The engine accepts owned, structurally validated rsomics_bamio::raw::RawRecord values and the reference lengths from their header. Before a mapped record can affect a column, it checks:

• reference ID and alignment coordinates;
• coordinate order across reference sequences and positions;
• CIGAR operation kinds, lengths, query span, reference span, and reference bounds;
• BAM CG:B,I long-CIGAR replacement and its placeholder span through the shared rsomics-bamio record contract.

Filtering is explicit product policy, but filtered mapped records still pass validation and advance the sorted input watermark. The engine can apply the HTSlib overlapping-mate quality adjustment. Its reusable BAQ realigner calculates standard or extended per-base alignment qualities, converts existing BQ and ZQ tags, and can either store the adjustment or apply it to base qualities. A column-preparation callback lets product consumers trigger BAQ after the pileup engine has accepted and overlap-adjusted the active records. Emitted columns borrow the active record arena and reuse projection buffers instead of allocating a second record vector at every position.

use rsomics_pileup::{PileupEngine, PileupOptions};

let mut engine = PileupEngine::new(reference_lengths, PileupOptions::default());
for record in records {
    engine.push(record)?;
    engine.drain(|column| {
        for entry in column.entries() {
            consume(entry.record(), entry.projection());
        }
        Ok::<_, ConsumerError>(())
    })?;
}
engine.finish()?;
engine.drain(consume_column)?;

Consumers that derive record-level data once can retain it for the record's active lifetime:

let mut engine = PileupEngine::<RecordState>::with_record_state(
    reference_lengths,
    PileupOptions::default(),
);
let state = RecordState::from(&record)?;
engine.push_with_state(record, state)?;
engine.drain(|column| {
    for entry in column.entries() {
        consume(entry.record(), entry.projection(), entry.state());
    }
    Ok::<_, ConsumerError>(())
})?;

rsomics-bam, rsomics-call, and rsomics-methyl are the named consumers. Their format, calling, methylation, and CLI policies remain outside this foundation.

Release contract

The unit suite covers complex CIGAR projection, all four FLAG predicate forms, sortedness, invalid coordinates and spans, long CIGAR, zero-reference-span records, and overlap adjustment. A live test compares text reconstructed from the public column API byte-for-byte with samtools 1.24 for matches, insertions, deletions, skips, padding, clipping, strand, head and tail markers, and matching, mismatching, insertion-bearing, and deletion-bearing overlapping mates.

rsomics-call covers full, overlap-ordered, and indel-triggered partial BAQ against bcftools 1.24. rsomics-bam mpileup supplies the second product contract across SAM, BAM, and CRAM, including default and recalculated BAQ, mate overlap adjustment, indel text encoding, and uncovered-position modes against samtools 1.24. The included engine benchmark covers 30× and 250× synthetic depth with and without the partial-BAQ trigger scan.

The projection, overlap, and BAQ behavior follows HTSlib 1.24 bam_plp, bcftools 1.24 mplp_realn, and HTSlib 1.24 sam_prob_realn and probaln_glocal, licensed under MIT/Expat. The retained notice is in LICENSES/HTSLIB-MIT.txt. This crate is licensed under MIT OR Apache-2.0.