lotrs 0.1.1

Pure-Rust bacterial subcellular localization predictor: a compact CNN (architecture inspired by DeepLoc) with independently-trained weights on UniProt/SwissProt (CC-BY). Predicts cytoplasm / inner-membrane / periplasm / outer-membrane / extracellular / cell-wall. Database-free, self-contained inference.
Documentation
//! lotrs — pure-Rust bacterial subcellular localization predictor.
//!
//! A compact convolutional network that reads a full protein sequence and predicts its
//! bacterial subcellular compartment. Architecture **inspired by DeepLoc** (Almagro
//! Armenteros et al. 2017) — a sequence CNN with global pooling — but this is an
//! independent clean-room implementation with its own code and its own weights, trained
//! from scratch on public UniProt/SwissProt (reviewed bacterial entries with experimental
//! localization, CC-BY 4.0). No DeepLoc source or weights are used.
//!
//! Inference is self-contained: weights embedded at compile time, every op hand-rolled
//! (one-hot encode, `conv1d` + ReLU, global avg+max pool, linear head). No ML runtime.
//!
//! ```
//! let m = lotrs::Model::embedded();
//! let p = m.predict(b"MSKIVKIIGREIIDSRGNPTVEAEVHLEGGFVGMAAAPSGASTGSRE");
//! println!("{} ({:.2})", p.label, p.prob);
//! ```

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

#[derive(Deserialize)]
struct Weights {
    #[serde(rename = "L")]
    l: usize,
    #[serde(rename = "C")]
    c: usize,
    k: usize,
    nsym: usize,
    aa_order: String,
    classes: Vec<String>,
    #[allow(dead_code)]
    n_conv: usize,
    conv1_w: Vec<Vec<Vec<f32>>>, // [C][nsym-1][k]
    conv1_b: Vec<f32>,
    conv2_w: Vec<Vec<Vec<f32>>>, // [C][C][k]
    conv2_b: Vec<f32>,
    conv3_w: Vec<Vec<Vec<f32>>>,
    conv3_b: Vec<f32>,
    conv4_w: Vec<Vec<Vec<f32>>>,
    conv4_b: Vec<f32>,
    type_w: Vec<Vec<f32>>, // [nclass][2*C]
    type_b: Vec<f32>,
}

/// A localization prediction.
#[derive(Debug, Clone)]
pub struct Prediction {
    /// Most probable compartment label.
    pub label: String,
    /// Softmax probability of `label`.
    pub prob: f32,
    /// Index of `label` in the model's class list.
    pub class_index: usize,
    /// Full softmax over all classes (aligned with [`Model::classes`]).
    pub probs: Vec<f32>,
}

/// A loaded lotrs model.
pub struct Model {
    w: Weights,
    /// aa byte -> index 1..=20 (0 = pad/unknown), matching training's AA_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::new();
    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())?;
        let mut aa_to_idx = [0usize; 256]; // default -> 0 (pad/unknown)
        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 })
    }

    /// The model's class labels (compartments), in output order.
    pub fn classes(&self) -> &[String] {
        &self.w.classes
    }

    /// Predict for many sequences in parallel (rayon). Equivalent to mapping
    /// [`Model::predict`] over `seqs` — identical results, one [`Prediction`] per input in
    /// order. Use for whole-genome / large batches; forward passes are independent.
    pub fn predict_many(&self, seqs: &[&[u8]]) -> Vec<Prediction> {
        use rayon::prelude::*;
        seqs.par_iter().map(|s| self.predict(s)).collect()
    }

    /// Predict the subcellular compartment for a protein sequence.
    pub fn predict(&self, aa: &[u8]) -> Prediction {
        let l = self.w.l;
        let c = self.w.c;
        let chan = self.w.nsym - 1; // one-hot channels after dropping pad (=20)

        // encode indices [L] (0 = pad/unknown), first L residues.
        let mut idx = vec![0usize; l];
        for t in 0..l.min(aa.len()) {
            idx[t] = self.aa_to_idx[aa[t] as usize];
        }
        // one-hot [chan][L]: index j (1..=chan) -> channel j-1; index 0 (pad) -> no channel
        let mut oh = vec![0.0f32; chan * l];
        for t in 0..l {
            let j = idx[t];
            if j >= 1 && j <= chan {
                oh[(j - 1) * l + t] = 1.0;
            }
        }
        // 4 conv+ReLU (same-pad)
        let h1 = conv1d_relu(&oh, chan, l, &self.conv_wf[0], &self.w.conv1_b, c, self.w.k);
        let h2 = conv1d_relu(&h1, c, l, &self.conv_wf[1], &self.w.conv2_b, c, self.w.k);
        let h3 = conv1d_relu(&h2, c, l, &self.conv_wf[2], &self.w.conv3_b, c, self.w.k);
        let h = conv1d_relu(&h3, c, l, &self.conv_wf[3], &self.w.conv4_b, c, self.w.k);

        // global avg-pool ++ max-pool over the FULL length L (no masking — matches training)
        let mut pooled = vec![0.0f32; 2 * c];
        for ci in 0..c {
            let base = ci * l;
            let mut sum = 0.0f32;
            let mut mx = f32::NEG_INFINITY;
            for t in 0..l {
                let v = h[base + t];
                sum += v;
                if v > mx {
                    mx = v;
                }
            }
            pooled[ci] = sum / l as f32;
            pooled[c + ci] = mx;
        }
        // linear head -> logits -> softmax
        let nclass = self.w.classes.len();
        let mut logits = vec![0.0f32; nclass];
        for k in 0..nclass {
            let mut s = self.w.type_b[k];
            let row = &self.w.type_w[k];
            for j in 0..2 * c {
                s += row[j] * pooled[j];
            }
            logits[k] = s;
        }
        let probs = softmax(&logits);
        let mut best = 0usize;
        for k in 1..nclass {
            if probs[k] > probs[best] {
                best = k;
            }
        }
        Prediction {
            label: self.w.classes[best].clone(),
            prob: probs[best],
            class_index: best,
            probs,
        }
    }
}

/// `conv1d` with `same` padding (k/2) followed by ReLU. `inp` is `[cin][L]` row-major,
/// `w` is flattened `[cout*cin*k]` (`(co*cin+ci)*k + dk`); returns `[cout][L]` row-major.
///
/// 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 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 weight layout move.
fn conv1d_relu(
    inp: &[f32],
    cin: usize,
    l: usize,
    w: &[f32],
    b: &[f32],
    cout: usize,
    k: usize,
) -> Vec<f32> {
    let pad = k as isize / 2;
    let mut out = vec![0.0f32; cout * l];
    for co in 0..cout {
        let orow = &mut out[co * l..co * l + l];
        for o in orow.iter_mut() {
            *o = b[co];
        }
        let wco = &w[co * cin * k..(co + 1) * cin * k];
        for ci in 0..cin {
            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 as isize - pad;
                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
}

fn softmax(x: &[f32]) -> Vec<f32> {
    let m = x.iter().cloned().fold(f32::NEG_INFINITY, f32::max);
    let mut e: Vec<f32> = x.iter().map(|v| (v - m).exp()).collect();
    let s: f32 = e.iter().sum();
    for v in &mut e {
        *v /= s;
    }
    e
}

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

    #[test]
    fn embedded_predicts() {
        let m = Model::embedded();
        let p = m.predict(b"MSKIVKIIGREIIDSRGNPTVEAEVHLEGGFVGMAAAPSGASTGSREALELRDGDKSRFLGKG");
        let s: f32 = p.probs.iter().sum();
        assert!((s - 1.0).abs() < 1e-3, "probs sum {s}");
        assert!(!p.label.is_empty());
    }
}