balrox 0.1.1

Pure-Rust learned bacterial gene/ORF quality scorer: a dilated temporal CNN (architecture inspired by Balrog) with independently-trained weights on RefSeq CDS, used to rerank/filter spurious ORF calls. Database-free, self-contained inference.
Documentation
//! balrox — pure-Rust learned bacterial gene / ORF quality scorer.
//!
//! A dilated temporal convolutional network that reads a candidate ORF's amino-acid
//! sequence and returns P(real protein-coding gene). Architecture **inspired by Balrog**
//! (Sommer & Salzberg, 2021) — a learned gene model — but this is an independent
//! clean-room implementation with its own code and its own weights, trained from scratch
//! on public RefSeq/GenBank bacterial CDS (positives) versus frame-shift-simulated and
//! shadow ORFs (negatives). No Balrog source or weights are used.
//!
//! Intended use inside bactars: an **additive reranker** over the faithful Prodigal port
//! (rustygal). rustygal still calls ORFs; balrox provides a score to down-rank/filter
//! borderline or spurious calls. It never replaces the gene caller.
//!
//! Inference is self-contained: weights embedded at compile time, every op hand-rolled
//! (embedding lookup, dilated `conv1d` + ReLU, masked global-average pool, linear head).
//!
//! ```
//! let m = balrox::Model::embedded();
//! let s = m.score(b"MSKIVKIIGREIIDSRGNPTVEAEVHLEGGFVGMAAAPSGASTGSRE");
//! assert!((0.0..=1.0).contains(&s));
//! ```

use serde::Deserialize;
use std::sync::OnceLock;

#[derive(Deserialize)]
struct Weights {
    #[serde(rename = "L")]
    l: usize,
    #[serde(rename = "C")]
    c: usize,
    k: usize,
    #[allow(dead_code)] // kept for schema completeness / round-trip
    nsym: usize,
    aa_order: String,
    dilations: Vec<usize>,
    embed_w: Vec<Vec<f32>>,          // [nsym][C]
    conv1_w: Vec<Vec<Vec<f32>>>,     // [C][C][k]
    conv1_b: Vec<f32>,
    conv2_w: Vec<Vec<Vec<f32>>>,
    conv2_b: Vec<f32>,
    conv3_w: Vec<Vec<Vec<f32>>>,
    conv3_b: Vec<f32>,
    conv4_w: Vec<Vec<Vec<f32>>>,
    conv4_b: Vec<f32>,
    score_w: Vec<Vec<f32>>,          // [1][C]
    score_b: Vec<f32>,               // [1]
}

/// A loaded balrox scorer.
pub struct Model {
    w: Weights,
    /// aa byte -> index 1..=20 (0 = pad/unknown), matching training's AA_TO_IDX.
    aa_to_idx: [usize; 256],
    /// Conv weights flattened to contiguous `[cout*cin*k]` per layer (row-major
    /// `(co*cin+ci)*k + dk`), so the hot loop reads them without pointer-chasing the
    /// nested `Vec<Vec<Vec<f32>>>`. Same values, same order — purely a memory layout.
    conv_wf: Vec<Vec<f32>>,
}

/// Flatten a `[cout][cin][k]` weight tensor to a contiguous `[cout*cin*k]` vector in
/// row-major order, preserving element order exactly.
fn flatten3(w: &[Vec<Vec<f32>>]) -> Vec<f32> {
    let mut v = Vec::with_capacity(w.len() * w.first().map_or(0, |a| a.len() * a.first().map_or(0, |b| b.len())));
    for a in w {
        for b in a {
            v.extend_from_slice(b);
        }
    }
    v
}

/// Trained weights, gzip-compressed and embedded at compile time (kept under the
/// crates.io size limit; decompressed once in [`Model::embedded`]).
const EMBEDDED_WEIGHTS_GZ: &[u8] = include_bytes!("../weights.json.gz");

impl Model {
    /// The model backed by the embedded trained weights (parsed once, cached).
    pub fn embedded() -> &'static Model {
        static M: OnceLock<Model> = OnceLock::new();
        M.get_or_init(|| {
            use std::io::Read;
            let mut s = String::new();
            flate2::read::GzDecoder::new(EMBEDDED_WEIGHTS_GZ)
                .read_to_string(&mut s)
                .expect("decompress embedded weights");
            Model::from_json(&s).expect("embedded weights parse")
        })
    }

    /// Load a model from a `weights.json` string.
    pub fn from_json(s: &str) -> Result<Model, String> {
        let w: Weights = serde_json::from_str(s).map_err(|e| e.to_string())?;
        // training: AA_TO_IDX = {aa: i+1}, unknown/pad -> 0
        let mut aa_to_idx = [0usize; 256];
        for (i, c) in w.aa_order.bytes().enumerate() {
            aa_to_idx[c as usize] = i + 1;
            aa_to_idx[c.to_ascii_lowercase() as usize] = i + 1;
        }
        let conv_wf = vec![
            flatten3(&w.conv1_w),
            flatten3(&w.conv2_w),
            flatten3(&w.conv3_w),
            flatten3(&w.conv4_w),
        ];
        Ok(Model { aa_to_idx, conv_wf, w })
    }

    /// Score many ORFs in parallel (rayon). Equivalent to mapping [`Model::score`] over
    /// `seqs` — same numeric results, one score per input in order. Use this for whole-
    /// genome / large batches; each forward pass is independent so it scales across cores.
    pub fn score_many(&self, seqs: &[&[u8]]) -> Vec<f32> {
        use rayon::prelude::*;
        seqs.par_iter().map(|s| self.score(s)).collect()
    }

    /// Score a candidate ORF's amino-acid sequence: P(real protein-coding gene) in [0,1].
    pub fn score(&self, aa: &[u8]) -> f32 {
        let l = self.w.l;
        let c = self.w.c;
        // encode to indices [L] (0 = pad/unknown); first L residues, zero-padded.
        let mut idx = vec![0usize; l];
        for t in 0..l.min(aa.len()) {
            idx[t] = self.aa_to_idx[aa[t] as usize];
        }
        // embedding lookup -> h [C][L]
        let mut h = vec![0.0f32; c * l];
        for t in 0..l {
            let row = &self.w.embed_w[idx[t]];
            for ch in 0..c {
                h[ch * l + t] = row[ch];
            }
        }
        // 4 dilated conv blocks (same-length, padding = d*(k/2)), ReLU
        let cbs = [
            &self.w.conv1_b,
            &self.w.conv2_b,
            &self.w.conv3_b,
            &self.w.conv4_b,
        ];
        for bi in 0..4 {
            let d = self.w.dilations[bi];
            h = dilated_conv1d_relu(&h, c, l, &self.conv_wf[bi], cbs[bi], self.w.k, d);
        }
        // masked global-average pool over non-pad positions
        let mut nvalid = 0usize;
        for t in 0..l {
            if idx[t] != 0 {
                nvalid += 1;
            }
        }
        let denom = nvalid.max(1) as f32;
        let mut pooled = vec![0.0f32; c];
        for ch in 0..c {
            let mut s = 0.0;
            for t in 0..l {
                if idx[t] != 0 {
                    s += h[ch * l + t];
                }
            }
            pooled[ch] = s / denom;
        }
        // linear score head + sigmoid
        let mut logit = self.w.score_b[0];
        for ch in 0..c {
            logit += self.w.score_w[0][ch] * pooled[ch];
        }
        1.0 / (1.0 + (-logit).exp())
    }
}

/// Dilated `conv1d` with same-length output (padding = `d*(k/2)`) followed by ReLU.
/// `inp`/output are `[C][L]` row-major; `w` is flattened `[C*C*k]` (`(co*C+ci)*k + dk`).
///
/// Loop order is `co -> ci -> dk -> t`: for each `(ci, dk)` tap the innermost loop is a
/// contiguous `out[t] += w * inp[t + shift]` AXPY (shift = `dk*d - pad`) over a branch-free
/// `t` range, which auto-vectorizes. Byte-identical to the naive `co -> t -> ci -> dk`
/// form: every output element still accumulates its in-bounds taps in `ci`-major, `dk`-minor
/// order, so the floating-point result is unchanged — only the loop nesting and the (already
/// contiguous) weight layout move.
fn dilated_conv1d_relu(
    inp: &[f32],
    c: usize,
    l: usize,
    w: &[f32],
    b: &[f32],
    k: usize,
    d: usize,
) -> Vec<f32> {
    let pad = (d * (k / 2)) as isize;
    let mut out = vec![0.0f32; c * l];
    for co in 0..c {
        let orow = &mut out[co * l..co * l + l];
        for o in orow.iter_mut() {
            *o = b[co];
        }
        let wco = &w[co * c * k..(co + 1) * c * k];
        for ci in 0..c {
            let irow = &inp[ci * l..ci * l + l];
            let wci = &wco[ci * k..ci * k + k];
            for dk in 0..k {
                let wt = wci[dk];
                let shift = (dk * d) as isize - pad;
                // Valid output positions: 0 <= t < l AND 0 <= t + shift < l.
                let (t0, t1) = if shift >= 0 {
                    (0usize, l.saturating_sub(shift as usize))
                } else {
                    (((-shift) as usize).min(l), l)
                };
                if t0 >= t1 {
                    continue;
                }
                let src = (t0 as isize + shift) as usize;
                for (o, &x) in orow[t0..t1].iter_mut().zip(&irow[src..src + (t1 - t0)]) {
                    *o += wt * x;
                }
            }
        }
        for o in orow.iter_mut() {
            if *o < 0.0 {
                *o = 0.0;
            }
        }
    }
    out
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn embedded_scores_in_range() {
        let m = Model::embedded();
        let s = m.score(b"MSKIVKIIGREIIDSRGNPTVEAEVHLEGGFVGMAAAPSGASTGSREALELRDGDKSRFLGKG");
        assert!((0.0..=1.0).contains(&s), "score {s}");
    }
}