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::path::{Path, PathBuf};

use roxmltree::Document;

use crate::error::{Med64Error, Result};

/// A workflow node from a `.moflo` XML protocol file.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MofloNode {
    pub key: String,
    pub id: String,
    pub settings: Vec<(String, String)>,
}

/// Parsed `.moflo` workflow describing how MED64 offline tools process recordings.
#[derive(Debug, Clone, PartialEq)]
pub struct MofloProtocol {
    pub mobius_version: Option<String>,
    pub workflow_basename: Option<String>,
    pub library_name: Option<String>,
    pub nodes: Vec<MofloNode>,
}

impl MofloProtocol {
    pub fn from_file(path: impl AsRef<Path>) -> Result<Self> {
        let path = path.as_ref();
        let xml = std::fs::read_to_string(path)
            .map_err(|source| Med64Error::Io { path: path.to_path_buf(), source })?;
        Self::parse(&xml)
            .map_err(|message| Med64Error::InvalidMoflo { path: path.to_path_buf(), message })
    }

    pub fn parse(xml: &str) -> std::result::Result<Self, String> {
        let doc = Document::parse(xml).map_err(|err| err.to_string())?;
        let root = doc.root_element();
        if root.tag_name().name() != "protocol" {
            return Err("expected root <protocol> element".into());
        }

        let mobius_version = find_text(root, &["protocol_settings", "mobius_version"]);
        let workflow_basename = find_text(root, &["protocol_settings", "workflow_basename"]);
        let library_name = find_direct_text(root, "library_name");

        let mut nodes = Vec::new();
        if let Some(node_list) = root.children().find(|n| n.has_tag_name("node_list")) {
            for node in node_list.children().filter(|n| n.has_tag_name("node")) {
                let key = find_direct_text(node, "key").unwrap_or_default();
                let id = find_direct_text(node, "id").unwrap_or_default();
                let mut settings = Vec::new();

                for child in node.children().filter(|n| n.has_tag_name("node_settings")) {
                    for setting in child.children().filter(|n| n.is_element()) {
                        let name = setting.tag_name().name().to_string();
                        let value = setting.text().unwrap_or("").trim().to_string();
                        settings.push((name, value));
                    }
                }

                nodes.push(MofloNode { key, id, settings });
            }
        }

        Ok(Self { mobius_version, workflow_basename, library_name, nodes })
    }

    /// Return replay nodes that reference `.modat` input files.
    pub fn replay_data_files(&self) -> Vec<String> {
        self.nodes
            .iter()
            .filter(|node| node.key == "replay_data")
            .filter_map(|node| {
                node.settings
                    .iter()
                    .find(|(key, _)| key == "filename")
                    .map(|(_, value)| value.clone())
            })
            .collect()
    }

    /// Resolve replay filenames relative to the workflow file's directory.
    pub fn resolve_replay_paths(&self, workflow_path: &Path) -> Vec<PathBuf> {
        let base_dir =
            workflow_path.parent().map(Path::to_path_buf).unwrap_or_else(|| PathBuf::from("."));

        self.replay_data_files()
            .into_iter()
            .map(|filename| base_dir.join(basename_from_any_path(&filename)))
            .collect()
    }
}

impl MofloProtocol {
    /// Serialize this protocol as Mobius-compatible `.moflo` XML.
    pub fn to_xml(&self) -> String {
        let mut xml = String::from("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<protocol>\n");
        if let Some(lib) = &self.library_name {
            xml.push_str(&format!("  <library_name>{}</library_name>\n", xml_escape(lib)));
        }
        xml.push_str("  <protocol_settings>\n");
        if let Some(v) = &self.mobius_version {
            xml.push_str(&format!("    <mobius_version>{}</mobius_version>\n", xml_escape(v)));
        }
        if let Some(b) = &self.workflow_basename {
            xml.push_str(&format!(
                "    <workflow_basename>{}</workflow_basename>\n",
                xml_escape(b)
            ));
        }
        xml.push_str("  </protocol_settings>\n  <node_list>\n");
        for node in &self.nodes {
            xml.push_str("    <node>\n");
            xml.push_str(&format!("      <key>{}</key>\n", xml_escape(&node.key)));
            xml.push_str(&format!("      <id>{}</id>\n", xml_escape(&node.id)));
            xml.push_str("      <node_settings>\n");
            for (k, v) in &node.settings {
                xml.push_str(&format!("        <{k}>{}</{k}>\n", xml_escape(v)));
            }
            xml.push_str("      </node_settings>\n    </node>\n");
        }
        xml.push_str("  </node_list>\n</protocol>\n");
        xml
    }

    pub fn write_to(&self, path: impl AsRef<Path>) -> Result<()> {
        let path = path.as_ref();
        std::fs::write(path, self.to_xml())
            .map_err(|source| Med64Error::WriteIo { path: path.to_path_buf(), source })
    }
}

/// Build a minimal replay → filter → spike-extract workflow.
pub fn write_analysis_moflo(
    path: impl AsRef<Path>,
    replay_filename: &str,
    highpass_hz: f64,
    lowpass_hz: f64,
) -> Result<()> {
    let protocol = MofloProtocol {
        mobius_version: Some("med64-rust".into()),
        workflow_basename: Some("Spike detection".into()),
        library_name: Some("electrophysiology".into()),
        nodes: vec![
            MofloNode {
                key: "replay_data".into(),
                id: "replay1".into(),
                settings: vec![("filename".into(), replay_filename.into())],
            },
            MofloNode {
                key: "filter_raw_data".into(),
                id: "hp1".into(),
                settings: vec![
                    ("filter_type".into(), "8".into()),
                    ("low_cutoff".into(), format!("{highpass_hz}")),
                ],
            },
            MofloNode {
                key: "filter_raw_data".into(),
                id: "lp1".into(),
                settings: vec![
                    ("filter_type".into(), "2".into()),
                    ("high_cutoff".into(), format!("{lowpass_hz}")),
                ],
            },
            MofloNode {
                key: "extract_spikes_advanced".into(),
                id: "spk1".into(),
                settings: vec![
                    ("rmsPercentage".into(), "500".into()),
                    ("thresholdType".into(), "Median".into()),
                    (
                        "posThresholds_mV".into(),
                        "0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0".into(),
                    ),
                    (
                        "negThresholds_mV".into(),
                        "0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0".into(),
                    ),
                    ("channelSpikeLimit_Hz".into(), "400".into()),
                ],
            },
            MofloNode {
                key: "export_raw_data".into(),
                id: "raw1".into(),
                settings: vec![
                    ("storageEnabled".into(), "true".into()),
                    ("all_in_one_file".into(), "true".into()),
                ],
            },
        ],
    };
    protocol.write_to(path)
}

fn xml_escape(s: &str) -> String {
    s.replace('&', "&amp;").replace('<', "&lt;").replace('>', "&gt;").replace('"', "&quot;")
}

fn basename_from_any_path(path: &str) -> &str {
    path.rsplit(['\\', '/']).next().filter(|name| !name.is_empty()).unwrap_or(path)
}

fn find_direct_text<'a>(node: roxmltree::Node<'a, 'a>, 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)
}

fn find_text<'a>(root: roxmltree::Node<'a, 'a>, path: &[&str]) -> Option<String> {
    let mut node = root;
    for tag in path {
        node = node.children().find(|child| child.has_tag_name(*tag))?;
    }
    node.text().map(str::trim).map(str::to_string)
}

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

    #[test]
    fn parses_sample_moflo() {
        let protocol =
            MofloProtocol::from_file(crate::fixture_paths::sample_data6_moflo()).unwrap();

        assert_eq!(protocol.library_name.as_deref(), Some("electrophysiology"));
        assert_eq!(protocol.workflow_basename.as_deref(), Some("Spike detection"));
        assert!(protocol.nodes.iter().any(|n| n.key == "replay_data"));

        let replays = protocol.replay_data_files();
        assert_eq!(replays.len(), 1);
        assert!(replays[0].ends_with("sample data6_3_3 nM CAP.modat"));

        let resolved = protocol.resolve_replay_paths(&crate::fixture_paths::sample_data6_moflo());
        assert!(resolved[0].ends_with("sample data6_3_3 nM CAP.modat"));
    }

    #[test]
    fn basename_handles_windows_paths() {
        assert_eq!(basename_from_any_path(r"C:\Users\foo\sample data6\trace.modat"), "trace.modat");
    }

    #[test]
    fn write_roundtrip() {
        let dir = std::env::temp_dir().join(format!("med64-moflo-{}", std::process::id()));
        let _ = std::fs::create_dir_all(&dir);
        let path = dir.join("out.moflo");
        write_analysis_moflo(&path, "sample.modat", 100.0, 2000.0).unwrap();
        let p = MofloProtocol::from_file(&path).unwrap();
        assert!(p.nodes.iter().any(|n| n.key == "replay_data"));
        assert_eq!(p.replay_data_files()[0], "sample.modat");
        let _ = std::fs::remove_file(path);
    }
}