openreadout-biophys 0.3.0

Readers for biophysics bench instruments such as ITC, surface plasmon resonance and Seahorse XF, part of OpenReadout
Documentation
//! The evaluation items of a Biacore T200 evaluation file (`.bme`): XML streams
//! `Evaluation/EvaluationItemN` (ISO-8859-1). Their fits — the evaluation software's kinetic and
//! affinity models with parameters, standard errors and Chi², and the curves each was fitted to —
//! are read as stored. Layout: `docs/formats/cytiva-biacore.md` § Evaluation files.

use std::collections::BTreeMap;

use openreadout_core::bytes::{latin1, until_nul};
use roxmltree::{Document, Node};

/// One evaluation item (a report-point table, plot, sensorgram overlay or analysis).
#[derive(Debug, Clone, PartialEq)]
pub(crate) struct EvalItem {
    /// `N` of `EvaluationItemN`.
    pub index: u32,
    /// The item's `ClassName` (`AffinityScreen`, `KineticsAffinity`, `Plot`, …).
    pub class: String,
    /// The item's `Name`.
    pub name: String,
    /// Fits the item holds.
    pub fits: usize,
}

/// One parameter of a fit.
#[derive(Debug, Clone, PartialEq)]
pub(crate) struct Param {
    /// What the value applies to (`0`, `0:1-32`): the text before the name.
    pub scope: String,
    /// Parameter name as the model names it (`KD`, `ka`, `kd`, `Rmax`, `offset`).
    pub name: String,
    pub value: f64,
    /// Standard error.
    pub se: f64,
}

/// One curve (concentration) of a fit's curve set.
#[derive(Debug, Clone, PartialEq)]
pub(crate) struct FitPoint {
    /// The subset's curve name (`Fc=2-1`).
    pub subset: String,
    pub file: f64,
    pub cycle: f64,
    pub sample: String,
    /// Molar concentration (M).
    pub concentration: f64,
    /// The concentration as entered, in `unit`.
    pub concentration_stated: f64,
    pub unit: String,
    /// The response the fit used (RU), when stored.
    pub response: f64,
    /// 1 included in the fit, 0 excluded, NaN when not stored.
    pub included: f64,
}

/// One fit.
#[derive(Debug, Clone, PartialEq)]
pub(crate) struct Fit {
    /// `N` of the item.
    pub item: u32,
    pub item_name: String,
    /// `ModelName` (`Steady State Affinity`, `1:1 Binding`).
    pub model: String,
    /// The model's expression or type (`Conc*Rmax/(Conc+KD)+offset`).
    pub expression: String,
    pub chi2: f64,
    pub sample: String,
    pub ligand: String,
    /// °C.
    pub temperature: f64,
    /// Curve names of the subsets (`Fc=2-1`), `;`-separated.
    pub curves: String,
    /// `fitStatus` where stored.
    pub status: String,
    pub params: Vec<Param>,
    /// Unit of each parameter, from `ReportParameters` (`KD (M)|KD`).
    pub units: BTreeMap<String, String>,
    pub points: Vec<FitPoint>,
}

fn child<'a, 'i>(n: Node<'a, 'i>, name: &str) -> Option<Node<'a, 'i>> {
    n.children()
        .find(|c| c.is_element() && c.has_tag_name(name))
}

fn text_of(n: Node<'_, '_>, name: &str) -> String {
    child(n, name)
        .and_then(|c| c.text())
        .unwrap_or("")
        .trim()
        .to_string()
}

fn num(s: &str) -> f64 {
    s.trim().parse::<f64>().unwrap_or(f64::NAN)
}

/// `id:name|value|error;…` (the id may itself contain `:`).
pub(crate) fn parse_parameters(s: &str) -> Vec<Param> {
    s.split(';')
        .filter_map(|e| {
            let (head, rest) = e.split_once('|')?;
            let (scope, name) = match head.rsplit_once(':') {
                Some((a, b)) => (a.trim(), b.trim()),
                None => ("", head.trim()),
            };
            if name.is_empty() {
                return None;
            }
            let mut it = rest.split('|');
            let value = num(it.next().unwrap_or(""));
            let se = num(it.next().unwrap_or(""));
            Some(Param {
                scope: scope.to_string(),
                name: name.to_string(),
                value,
                se,
            })
        })
        .collect()
}

/// `KD (M)|KD;Rmax (RU)|Rmax` -> {KD: M, Rmax: RU}.
pub(crate) fn parse_units(s: &str) -> BTreeMap<String, String> {
    s.split(';')
        .filter_map(|e| {
            let (label, name) = e.split_once('|')?;
            let unit = label.rsplit_once('(')?.1.strip_suffix(')')?.trim();
            (!unit.is_empty()).then(|| (name.trim().to_string(), unit.to_string()))
        })
        .collect()
}

/// The curves of a `CurveSet` element and its subset names.
fn curve_set(cs: Node<'_, '_>) -> (Vec<FitPoint>, Vec<String>) {
    let mut points = Vec::new();
    let mut names = Vec::new();
    for sub in cs
        .children()
        .filter(|c| c.is_element() && c.tag_name().name().starts_with("Subset"))
    {
        let subset = text_of(sub, "CurveName");
        names.push(subset.clone());
        for cv in sub.children().filter(|c| {
            c.is_element()
                && c.tag_name()
                    .name()
                    .strip_prefix("Curve")
                    .is_some_and(|d| !d.is_empty() && d.bytes().all(|b| b.is_ascii_digit()))
        }) {
            let inj = child(cv, "Injections").and_then(|i| child(i, "Injection"));
            let (conc, stated, response) = match inj {
                Some(i) => (
                    num(&text_of(i, "MolarConcentration")),
                    num(&text_of(i, "Concentration")),
                    num(&text_of(i, "Response")),
                ),
                None => (f64::NAN, f64::NAN, f64::NAN),
            };
            let included = match text_of(cv, "Included").as_str() {
                "true" => 1.0,
                "false" => 0.0,
                _ => f64::NAN,
            };
            points.push(FitPoint {
                subset: subset.clone(),
                file: num(&text_of(cv, "FileIndex")),
                cycle: num(&text_of(cv, "CycleNumber")),
                sample: text_of(cv, "SampleName"),
                concentration: conc,
                concentration_stated: stated,
                unit: text_of(cv, "ConcUnit"),
                response,
                included,
            });
        }
    }
    (points, names)
}

/// A fit from its model element (`model` or `FitN`), curve set and key.
fn fit_of(
    item: &EvalItem,
    model: Node<'_, '_>,
    cs: Option<Node<'_, '_>>,
    key: Option<Node<'_, '_>>,
    status: String,
) -> Fit {
    let (points, names) = cs.map(curve_set).unwrap_or_default();
    let pick = |cs_name: &str, key_name: &str| -> String {
        let a = cs.map(|c| text_of(c, cs_name)).unwrap_or_default();
        if a.is_empty() {
            key.map(|k| text_of(k, key_name)).unwrap_or_default()
        } else {
            a
        }
    };
    let curves = if names.iter().any(|n| !n.is_empty()) {
        names.join(";")
    } else {
        key.map(|k| text_of(k, "curveName")).unwrap_or_default()
    };
    Fit {
        item: item.index,
        item_name: item.name.clone(),
        model: model.attribute("ModelName").unwrap_or("").to_string(),
        expression: text_of(model, "Model"),
        chi2: num(&text_of(model, "Chi2")),
        sample: pick("SampleName", "sampleName"),
        ligand: pick("LigandName", "ligandName"),
        temperature: num(&pick("Temperature", "temperature")),
        curves,
        status,
        params: parse_parameters(&text_of(model, "Parameters")),
        units: parse_units(&text_of(model, "ReportParameters")),
        points,
    }
}

/// Parse one item stream (ISO-8859-1 XML).
pub(crate) fn parse_item(index: u32, bytes: &[u8]) -> Result<(EvalItem, Vec<Fit>), String> {
    let text = latin1(until_nul(bytes));
    let doc = Document::parse(&text).map_err(|e| format!("EvaluationItem{index}: {e}"))?;
    let root = doc.root_element();
    let mut item = EvalItem {
        index,
        class: root.attribute("ClassName").unwrap_or("").to_string(),
        name: text_of(root, "Name"),
        fits: 0,
    };
    let mut fits = Vec::new();
    // the older layout: modelFits/modelFits/modelFit, each with its own curve set and key
    for mf in root
        .descendants()
        .filter(|n| n.is_element() && n.has_tag_name("modelFit"))
    {
        let Some(model) = child(mf, "model") else {
            continue;
        };
        let cs = child(mf, "curveSet").and_then(|c| child(c, "CurveSet"));
        fits.push(fit_of(
            &item,
            model,
            cs,
            child(mf, "key"),
            text_of(mf, "fitStatus"),
        ));
    }
    // the newer layout: Fits/FitN beside the item's CurveSet
    if let Some(fs) = child(root, "Fits") {
        let cs = child(root, "CurveSet");
        for f in fs.children().filter(|c| {
            c.is_element()
                && c.tag_name()
                    .name()
                    .strip_prefix("Fit")
                    .is_some_and(|d| !d.is_empty() && d.bytes().all(|b| b.is_ascii_digit()))
        }) {
            fits.push(fit_of(&item, f, cs, None, String::new()));
        }
    }
    item.fits = fits.len();
    Ok((item, fits))
}

#[cfg(test)]
mod tests {
    #![allow(clippy::float_cmp)] // exact values
    use super::*;

    #[test]
    fn parameters_and_units() {
        let p = parse_parameters("0:KD|6.5E-05|4.3E-06;0:1-32:ka|3396690.9|1964.4;0:offset|0|");
        assert_eq!(p.len(), 3);
        assert_eq!((p[0].scope.as_str(), p[0].name.as_str()), ("0", "KD"));
        assert_eq!(p[0].value, 6.5e-5);
        assert_eq!((p[1].scope.as_str(), p[1].name.as_str()), ("0:1-32", "ka"));
        assert!(p[2].se.is_nan());
        let u = parse_units("KD (M)|KD;Rmax (RU)|Rmax;offset (RU)|offset;x|y");
        assert_eq!(u.get("KD").map(String::as_str), Some("M"));
        assert_eq!(u.len(), 3);
    }

    #[test]
    fn both_layouts() {
        let old = "<EvaluationItem7 ClassName=\"AffinityScreen\"><Name>Affinity Screen</Name><modelFits><modelFits><modelFit><curveSet><CurveSet><SampleName>C1</SampleName><Temperature>20</Temperature><Subset0><CurveName>Fc=2-1</CurveName><Curve0><FileIndex>1</FileIndex><CycleNumber>14</CycleNumber><SampleName>C1</SampleName><ConcUnit>\u{b5}M</ConcUnit><Injections><Injection><Concentration>1</Concentration><MolarConcentration>1E-06</MolarConcentration><Response>2.5</Response></Injection></Injections><Included>true</Included></Curve0></Subset0></CurveSet></curveSet><model ModelName=\"Steady State Affinity\"><Model>Conc*Rmax/(Conc+KD)+offset</Model><Chi2>0.11</Chi2><Parameters>0:KD|6.5E-05|4.3E-06</Parameters><ReportParameters>KD (M)|KD</ReportParameters></model><fitStatus>Cleared</fitStatus></modelFit></modelFits></modelFits></EvaluationItem7>";
        let bytes: Vec<u8> = old.chars().map(|c| c as u8).collect();
        let (item, fits) = parse_item(3, &bytes).unwrap();
        assert_eq!(item.class, "AffinityScreen");
        assert_eq!(fits.len(), 1);
        let f = &fits[0];
        assert_eq!(f.sample, "C1");
        assert_eq!(f.curves, "Fc=2-1");
        assert_eq!(f.points[0].unit, "\u{b5}M");
        assert_eq!(f.points[0].included, 1.0);
        assert_eq!(f.points[0].concentration, 1e-6);
        assert_eq!(f.status, "Cleared");
        let new = "<E ClassName=\"KineticsAffinity\"><Name>K</Name><CurveSet><SampleName>S</SampleName><LigandName>L</LigandName><Subset0><CurveName>Fc=2-1</CurveName></Subset0></CurveSet><Fits><Fit0 ModelName=\"1:1 Binding\"><Chi2>1.5</Chi2><Parameters>0:1-32:ka|3E6|2E3</Parameters></Fit0></Fits></E>";
        let (_, fits) = parse_item(1, new.as_bytes()).unwrap();
        assert_eq!(fits[0].model, "1:1 Binding");
        assert_eq!(fits[0].ligand, "L");
        assert_eq!(fits[0].params[0].name, "ka");
        assert!(parse_item(0, b"<a>").is_err());
    }
}