med64 0.0.2

Headless MED64 electrophysiology toolkit: .modat I/O, spike/burst analysis, assays, spike-rate maps, and CSV/HTML/SVG/HDF5 export
Documentation
use std::collections::{HashMap, VecDeque};

use crate::moflo::MofloProtocol;

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WorkflowLink {
    pub producer_id: String,
    pub receiver_id: String,
    pub datatype: String,
}

#[derive(Debug, Clone)]
pub struct WorkflowNodeRef {
    pub id: String,
    pub key: String,
    pub settings: Vec<(String, String)>,
}

#[derive(Debug, Clone)]
pub struct WorkflowGraph {
    pub nodes: HashMap<String, WorkflowNodeRef>,
    pub links: Vec<WorkflowLink>,
}

impl WorkflowGraph {
    pub fn from_protocol(protocol: &MofloProtocol, links: &[WorkflowLink]) -> Self {
        let nodes = protocol
            .nodes
            .iter()
            .map(|node| {
                (
                    node.id.clone(),
                    WorkflowNodeRef {
                        id: node.id.clone(),
                        key: node.key.clone(),
                        settings: node.settings.clone(),
                    },
                )
            })
            .collect();
        Self { nodes, links: links.to_vec() }
    }

    /// Topological order of compute nodes (excludes display-only sinks).
    pub fn execution_order(&self) -> Vec<String> {
        let mut indegree: HashMap<String, usize> = self
            .nodes
            .iter()
            .filter(|(_, node)| is_compute_key(&node.key))
            .map(|(id, _)| (id.clone(), 0))
            .collect();
        let mut adj: HashMap<String, Vec<String>> = HashMap::new();

        for link in &self.links {
            if !indegree.contains_key(&link.producer_id)
                || !indegree.contains_key(&link.receiver_id)
            {
                continue;
            }
            *indegree.entry(link.receiver_id.clone()).or_default() += 1;
            adj.entry(link.producer_id.clone()).or_default().push(link.receiver_id.clone());
        }

        let mut queue: VecDeque<String> =
            indegree.iter().filter(|(_, &deg)| deg == 0).map(|(id, _)| id.clone()).collect();

        let mut order = Vec::new();
        while let Some(id) = queue.pop_front() {
            order.push(id.clone());
            if let Some(nexts) = adj.get(&id) {
                for next in nexts {
                    if let Some(entry) = indegree.get_mut(next) {
                        *entry -= 1;
                        if *entry == 0 {
                            queue.push_back(next.clone());
                        }
                    }
                }
            }
        }
        order
    }

    pub fn node(&self, id: &str) -> Option<&WorkflowNodeRef> {
        self.nodes.get(id)
    }

    pub fn filter_chain_hz(&self) -> Vec<f64> {
        let mut cutoffs = Vec::new();
        for node in self.nodes.values() {
            if node.key == "filter_raw_data" {
                if let Some((_, value)) = node.settings.iter().find(|(k, _)| k == "filter_param") {
                    if let Ok(hz) = value.parse::<f64>() {
                        cutoffs.push(hz);
                    }
                }
            }
        }
        cutoffs.sort_by(|a, b| a.partial_cmp(b).unwrap());
        cutoffs
    }

    /// True when the high-cutoff (LP) stage uses Bessel coefficients.
    pub fn lowpass_is_bessel(&self) -> bool {
        let mut lp_nodes: Vec<_> =
            self.nodes.values().filter(|n| n.key == "filter_raw_data").collect();
        lp_nodes.sort_by_key(|n| n.id.clone());
        lp_nodes.last().is_some_and(|node| {
            node.settings.iter().any(|(k, v)| {
                (k == "filter_name" && v.eq_ignore_ascii_case("Bessel"))
                    || (k == "lpf_type" && v.eq_ignore_ascii_case("Bessel"))
            })
        })
    }

    pub fn spike_settings(&self) -> Option<&WorkflowNodeRef> {
        self.nodes.values().find(|node| node.key == "extract_spikes_advanced")
    }

    pub fn replay_node(&self) -> Option<&WorkflowNodeRef> {
        self.nodes.values().find(|node| node.key == "replay_data")
    }

    pub fn nodes_by_key<'a>(&'a self, key: &str) -> Vec<&'a WorkflowNodeRef> {
        self.nodes.values().filter(|n| n.key == key).collect()
    }

    pub fn wants_filtered_export(&self) -> bool {
        self.nodes_by_key("export_raw_data").iter().any(|n| {
            setting_bool(n, "storageEnabled").unwrap_or(true)
                || setting_bool(n, "all_in_one_file").unwrap_or(false)
        })
    }

    pub fn save_spike_nodes(&self) -> Vec<&WorkflowNodeRef> {
        self.nodes_by_key("save_spike_data")
    }

    pub fn save_freq_nodes(&self) -> Vec<&WorkflowNodeRef> {
        self.nodes_by_key("save_freq_data")
    }
}

fn setting_bool(node: &WorkflowNodeRef, key: &str) -> Option<bool> {
    node.settings.iter().find(|(k, _)| k == key).map(|(_, v)| v.eq_ignore_ascii_case("true"))
}

fn is_compute_key(key: &str) -> bool {
    matches!(
        key,
        "replay_data"
            | "filter_raw_data"
            | "extract_spikes_advanced"
            | "save_spike_data"
            | "compute_spike_freqs"
            | "save_freq_data"
            | "export_raw_data"
    )
}

pub fn parse_links(xml: &str) -> Result<Vec<WorkflowLink>, String> {
    let doc = roxmltree::Document::parse(xml).map_err(|err| err.to_string())?;
    let root = doc.root_element();
    let mut links = Vec::new();
    if let Some(link_list) = root.children().find(|n| n.has_tag_name("link_list")) {
        for link in link_list.children().filter(|n| n.has_tag_name("link")) {
            let producer = child_text(link, "producer_id").unwrap_or_default();
            let receiver = child_text(link, "receiver_id").unwrap_or_default();
            let datatype = child_text(link, "datatype").unwrap_or_default();
            links.push(WorkflowLink { producer_id: producer, receiver_id: receiver, datatype });
        }
    }
    Ok(links)
}

fn child_text(node: roxmltree::Node<'_, '_>, tag: &str) -> Option<String> {
    node.children()
        .find(|child| child.has_tag_name(tag))
        .and_then(|child| child.text())
        .map(str::trim)
        .map(str::to_string)
}

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

    /// The fixture is VENDORED (`src/workflow/testdata/`) rather than read from
    /// [`crate::fixture_paths::data_dir`]. It used to be read from there, and when that
    /// file was replaced the test began failing for reasons that had nothing to
    /// do with the graph code. A unit test must not depend on a mutable file
    /// outside the repository.
    const SPIKE_DETECTION_MOFLO: &str = include_str!("testdata/spike_detection.moflo");

    fn order_of(xml: &str) -> Vec<String> {
        let protocol = MofloProtocol::parse(xml).unwrap();
        let links = parse_links(xml).unwrap();
        WorkflowGraph::from_protocol(&protocol, &links).execution_order()
    }

    #[test]
    fn orders_sample_workflow() {
        let order = order_of(SPIKE_DETECTION_MOFLO);

        // execution_order() yields node IDs, not node KEYS. The previous
        // assertions looked for "replay_data" and "extract_spikes", which are
        // <key> values; the ids here are replay1/hp1/lp1/spk1/raw1. Checking
        // the wrong field made the test both wrong and vacuously weak.
        assert_eq!(
            order,
            vec!["replay1", "hp1", "lp1", "spk1", "raw1"],
            "replay -> highpass -> lowpass -> spikes -> export"
        );
    }

    #[test]
    fn dependencies_precede_dependents() {
        let order = order_of(SPIKE_DETECTION_MOFLO);
        let at = |id: &str| order.iter().position(|n| n == id).expect(id);
        assert!(at("replay1") < at("hp1"), "source must precede its filter");
        assert!(at("hp1") < at("lp1"), "highpass must precede lowpass");
        assert!(at("lp1") < at("spk1"), "filtering must precede detection");
    }

    /// Display nodes are UI-only and must be dropped from the compute order.
    /// The vendored fixture contains none, so the original assertion could
    /// never fail; this supplies one.
    #[test]
    fn display_nodes_are_excluded() {
        let xml = SPIKE_DETECTION_MOFLO.replace(
            "</node_list>",
            "  <node>\n\
             \x20   <key>display_spike_waveform</key>\n\
             \x20   <id>display_wave1</id>\n\
             \x20 </node>\n\
             </node_list>",
        );
        let order = order_of(&xml);
        assert!(
            !order.iter().any(|id| id.starts_with("display_")),
            "display node leaked into the execution order: {order:?}"
        );
        assert!(order.iter().any(|id| id == "spk1"), "real nodes still present");
    }
}