ionic-rs 0.2.0

Streamable binary format for mass-spectrometry data: lossless mzML conversion, random access, WebAssembly support
Documentation
use std::{
    collections::{HashMap, HashSet},
    sync::OnceLock,
};

use crate::{
    ion::{
        attr_meta::*,
        decoder::decode::{Metadatum, MetadatumValue},
        utilities::assign_attributes,
    },
    mzml::{
        schema::{SchemaNode, SchemaTree, TagId, schema},
        structs::{MzML, Spectrum},
    },
    utilities::test::mzml as parse_mzml_cached,
};

static MZML_CACHE: OnceLock<MzML> = OnceLock::new();

const MZML_PATH: &str = "data/mzml/test.mzML";
const ION_PATH: &str = "data/ion/test.ion";

fn spectra_meta_from_test_ion() -> Vec<Metadatum> {
    super::meta::spectra_metadata(ION_PATH)
}

fn find_node_by_tag(tree: &SchemaTree, tag: TagId) -> Option<&SchemaNode> {
    if let Some(n) = tree.root_by_tag(tag) {
        return Some(n);
    }
    for root in tree.roots.values() {
        let mut stack = vec![root];
        while let Some(node) = stack.pop() {
            if node.self_tags.contains(&tag) {
                return Some(node);
            }
            stack.extend(node.children.values());
        }
    }
    None
}

fn schema_attrs_for_tag(tag: TagId) -> &'static HashMap<String, Vec<String>> {
    let s = schema();
    let node =
        find_node_by_tag(s, tag).unwrap_or_else(|| panic!("schema missing node for {tag:?}"));
    &node.attributes
}

fn parse_tail(accession: &str) -> Option<AccessionTail> {
    let (cv, tail) = accession.split_once(':')?;
    if cv != CV_REF_ATTR {
        return None;
    }
    tail.parse::<u32>().ok().map(AccessionTail::from_raw)
}

pub(crate) fn tail_to_field_key(tail: AccessionTail) -> Option<&'static str> {
    match tail {
        ACC_ATTR_ID => Some("id"),
        ACC_ATTR_REF => Some("ref"),
        ACC_ATTR_LOCATION => Some("location"),
        ACC_ATTR_START_TIME_STAMP => Some("start_time_stamp"),
        ACC_ATTR_DEFAULT_INSTRUMENT_CONFIGURATION_REF => {
            Some("default_instrument_configuration_ref")
        }
        ACC_ATTR_DEFAULT_SOURCE_FILE_REF => Some("default_source_file_ref"),
        ACC_ATTR_SAMPLE_REF => Some("sample_ref"),
        ACC_ATTR_DEFAULT_DATA_PROCESSING_REF => Some("default_data_processing_ref"),
        ACC_ATTR_DATA_PROCESSING_REF => Some("data_processing_ref"),
        ACC_ATTR_SOURCE_FILE_REF => Some("source_file_ref"),
        ACC_ATTR_NATIVE_ID => Some("native_id"),
        ACC_ATTR_SPOT_ID => Some("spot_id"),
        ACC_ATTR_EXTERNAL_SPECTRUM_ID => Some("external_spectrum_id"),
        ACC_ATTR_SPECTRUM_REF => Some("spectrum_ref"),
        ACC_ATTR_SCAN_SETTINGS_REF => Some("scan_settings_ref"),
        ACC_ATTR_INSTRUMENT_CONFIGURATION_REF => Some("instrument_configuration_ref"),
        ACC_ATTR_SOFTWARE_REF => Some("software_ref"),
        ACC_ATTR_VERSION => Some("version"),
        ACC_ATTR_COUNT => Some("count"),
        ACC_ATTR_ORDER => Some("order"),
        ACC_ATTR_INDEX => Some("index"),
        ACC_ATTR_SCAN_NUMBER => Some("scan_number"),
        ACC_ATTR_DEFAULT_ARRAY_LENGTH => Some("default_array_length"),
        ACC_ATTR_ARRAY_LENGTH => Some("array_length"),
        ACC_ATTR_ENCODED_LENGTH => Some("encoded_length"),
        ACC_ATTR_MS_LEVEL => Some("ms_level"),
        _ => None,
    }
}

fn find_by_tail(meta: &[Metadatum], tail: AccessionTail) -> Option<&Metadatum> {
    meta.iter().find(|m| {
        m.accession
            .as_deref()
            .and_then(parse_tail)
            .is_some_and(|t| t == tail)
    })
}

fn assert_meta_value_equiv(a: &MetadatumValue, b: &MetadatumValue, ctx: &str) {
    match (a, b) {
        (MetadatumValue::Text(x), MetadatumValue::Text(y)) => assert_eq!(x, y, "{ctx}"),
        (MetadatumValue::Number(x), MetadatumValue::Number(y)) => {
            let dx = (x - y).abs();
            assert!(dx <= 1e-9, "{ctx}: {x} != {y}");
        }
        (MetadatumValue::Text(x), MetadatumValue::Number(y)) => {
            let px = x.parse::<f64>().unwrap_or(f64::NAN);
            let dx = (px - y).abs();
            assert!(dx <= 1e-9, "{ctx}: Text({x}) != Number({y})");
        }
        (MetadatumValue::Number(x), MetadatumValue::Text(y)) => {
            let py = y.parse::<f64>().unwrap_or(f64::NAN);
            let dx = (x - py).abs();
            assert!(dx <= 1e-9, "{ctx}: Number({x}) != Text({y})");
        }
        _ => panic!("{ctx}: type mismatch: {a:?} vs {b:?}"),
    }
}

fn candidate_schema_attr_tails_for_owner(
    meta: &[Metadatum],
    id: u32,
    schema_attrs: &HashMap<String, Vec<String>>,
) -> HashSet<AccessionTail> {
    let mut tails = HashSet::new();

    for m in meta.iter().filter(|m| m.id == id) {
        let Some(acc) = m.accession.as_deref() else {
            continue;
        };
        let Some(tail) = parse_tail(acc) else {
            continue;
        };
        let Some(k) = tail_to_field_key(tail) else {
            continue;
        };

        if schema_attrs.contains_key(k) {
            tails.insert(tail);
        }
    }

    tails
}

fn find_id_by_tail_text(meta: &[Metadatum], tag: TagId, tail: AccessionTail, text: &str) -> u32 {
    meta.iter()
        .find(|m| {
            m.tag_id == tag
                && m.accession.as_deref().and_then(parse_tail) == Some(tail)
                && matches!(&m.value, MetadatumValue::Text(t) if t == text)
        })
        .unwrap_or_else(|| panic!("cannot find id for {tag:?} tail={tail:?} text={text:?}"))
        .id
}

#[test]
fn assign_attrs_spectrum_list_ion_equiv_schema_subset() {
    let mzml = parse_mzml_cached(&MZML_CACHE, MZML_PATH);
    let sl = mzml
        .run
        .spectrum_list
        .as_ref()
        .expect("spectrumList parsed");

    let ion_meta = spectra_meta_from_test_ion();
    let schema_attrs = schema_attrs_for_tag(TagId::SpectrumList);

    let expected_ddpr = sl
        .default_data_processing_ref
        .as_deref()
        .expect("mzML spectrumList default_data_processing_ref present");

    let id = find_id_by_tail_text(
        &ion_meta,
        TagId::SpectrumList,
        ACC_ATTR_DEFAULT_DATA_PROCESSING_REF,
        expected_ddpr,
    );

    let parent_index = 0u32;
    let generated = assign_attributes(sl, TagId::SpectrumList, id, parent_index);

    let tails = candidate_schema_attr_tails_for_owner(&ion_meta, id, schema_attrs);
    assert!(
        !tails.is_empty(),
        "no schema-listed ATTR attrs found for SpectrumList id={id}"
    );

    for tail in tails {
        let b = ion_meta
            .iter()
            .find(|m| m.id == id && m.accession.as_deref().and_then(parse_tail) == Some(tail))
            .unwrap_or_else(|| panic!("ion missing tail={tail} for id={id}"));

        let g = find_by_tail(&generated, tail)
            .unwrap_or_else(|| panic!("generated meta missing tail={tail}"));

        assert_eq!(
            g.tag_id,
            TagId::SpectrumList,
            "generated tag_id wrong for tail={tail}"
        );
        assert_meta_value_equiv(&b.value, &g.value, &format!("tail={tail}"));
    }

    assert!(
        generated.iter().all(|m| {
            m.accession
                .as_deref()
                .map(|a| a.starts_with(CV_REF_ATTR))
                .unwrap_or(true)
        }),
        "generated assign_attributes should only emit {CV_REF_ATTR}:* accessions: {generated:#?}"
    );
}

#[test]
fn assign_attrs_spectrum_first_ion_equiv_schema_subset() {
    let mzml = parse_mzml_cached(&MZML_CACHE, MZML_PATH);
    let sl = mzml
        .run
        .spectrum_list
        .as_ref()
        .expect("spectrumList parsed");
    let s0 = &sl.spectra[0];

    let ion_meta = spectra_meta_from_test_ion();
    let schema_attrs = schema_attrs_for_tag(TagId::Spectrum);

    let id = find_id_by_tail_text(&ion_meta, TagId::Spectrum, ACC_ATTR_ID, s0.id.as_str());

    let parent_index = 0u32;
    let generated = assign_attributes(s0, TagId::Spectrum, id, parent_index);

    let tails = candidate_schema_attr_tails_for_owner(&ion_meta, id, schema_attrs);
    assert!(
        !tails.is_empty(),
        "no schema-listed ATTR attrs found for Spectrum id={id}"
    );

    for tail in tails {
        let b = ion_meta
            .iter()
            .find(|m| m.id == id && m.accession.as_deref().and_then(parse_tail) == Some(tail))
            .unwrap_or_else(|| panic!("ion missing tail={tail} for id={id}"));

        let g = find_by_tail(&generated, tail)
            .unwrap_or_else(|| panic!("generated meta missing tail={tail}"));

        assert_eq!(
            g.tag_id,
            TagId::Spectrum,
            "generated tag_id wrong for tail={tail}"
        );
        assert_meta_value_equiv(&b.value, &g.value, &format!("tail={tail}"));
    }
}

#[test]
fn assign_attrs_spectrum_last_ion_equiv_schema_subset() {
    let mzml = parse_mzml_cached(&MZML_CACHE, MZML_PATH);
    let sl = mzml
        .run
        .spectrum_list
        .as_ref()
        .expect("spectrumList parsed");
    let s_last: &Spectrum = sl.spectra.last().expect("last spectrum");

    let ion_meta = spectra_meta_from_test_ion();
    let schema_attrs = schema_attrs_for_tag(TagId::Spectrum);

    let id = find_id_by_tail_text(&ion_meta, TagId::Spectrum, ACC_ATTR_ID, s_last.id.as_str());

    let parent_index = 0u32;
    let generated = assign_attributes(s_last, TagId::Spectrum, id, parent_index);

    let tails = candidate_schema_attr_tails_for_owner(&ion_meta, id, schema_attrs);
    assert!(
        !tails.is_empty(),
        "no schema-listed ATTR attrs found for Spectrum id={id}"
    );

    for tail in tails {
        let b = ion_meta
            .iter()
            .find(|m| m.id == id && m.accession.as_deref().and_then(parse_tail) == Some(tail))
            .unwrap_or_else(|| panic!("ion missing tail={tail} for id={id}"));

        let g = find_by_tail(&generated, tail)
            .unwrap_or_else(|| panic!("generated meta missing tail={tail}"));

        assert_eq!(
            g.tag_id,
            TagId::Spectrum,
            "generated tag_id wrong for tail={tail}"
        );
        assert_meta_value_equiv(&b.value, &g.value, &format!("tail={tail}"));
    }
}