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
//! Activation / fast-burst onset maps (activation / FBO).

use serde::{Deserialize, Serialize};

use crate::analysis::{run_analysis, AnalysisOptions, SpikeTrain};
use crate::error::Result;
use std::path::Path;

#[derive(Debug, Clone)]
pub struct ActivationOptions {
    pub analysis: AnalysisOptions,
    pub grid_cols: usize,
    pub grid_rows: usize,
    /// Window (ms) after earliest array spike defining an activation wave.
    pub wave_window_ms: f64,
}

impl Default for ActivationOptions {
    fn default() -> Self {
        Self {
            analysis: AnalysisOptions { max_blocks: Some(20), ..AnalysisOptions::default() },
            grid_cols: 8,
            grid_rows: 8,
            wave_window_ms: 50.0,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ActivationCell {
    pub channel: usize,
    pub row: usize,
    pub col: usize,
    pub activation_ms: Option<f64>,
    pub delay_ms: Option<f64>,
    pub participated: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ActivationReport {
    pub path: std::path::PathBuf,
    pub origin_channel: Option<usize>,
    pub origin_time_ms: Option<f64>,
    pub participating: usize,
    pub cells: Vec<ActivationCell>,
}

/// First-spike activation map relative to the earliest electrode in a wave.
pub fn activation_map(
    path: impl AsRef<Path>,
    options: &ActivationOptions,
) -> Result<ActivationReport> {
    let path = path.as_ref();
    let report = run_analysis(path, &options.analysis)?;
    Ok(activation_from_spikes(path, &report.spikes, options))
}

pub fn activation_from_spikes(
    path: impl AsRef<Path>,
    train: &SpikeTrain,
    options: &ActivationOptions,
) -> ActivationReport {
    let mut first: std::collections::BTreeMap<usize, f64> = std::collections::BTreeMap::new();
    for spike in &train.spikes {
        first
            .entry(spike.channel)
            .and_modify(|t| *t = t.min(spike.within_trace_time_ms))
            .or_insert(spike.within_trace_time_ms);
    }
    let origin = first.iter().min_by(|a, b| a.1.partial_cmp(b.1).unwrap()).map(|(&c, &t)| (c, t));
    let (_origin_ch, origin_t) = origin.unwrap_or((0, 0.0));

    let n = options.grid_rows * options.grid_cols;
    let mut cells = Vec::with_capacity(n);
    let mut participating = 0usize;
    for ch in 0..n {
        let act = first.get(&ch).copied();
        let participated = act.is_some_and(|t| (t - origin_t).abs() <= options.wave_window_ms);
        if participated {
            participating += 1;
        }
        cells.push(ActivationCell {
            channel: ch,
            row: ch / options.grid_cols,
            col: ch % options.grid_cols,
            activation_ms: act,
            delay_ms: act.map(|t| t - origin_t),
            participated,
        });
    }

    ActivationReport {
        path: path.as_ref().to_path_buf(),
        origin_channel: origin.map(|(c, _)| c),
        origin_time_ms: origin.map(|(_, t)| t),
        participating,
        cells,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::analysis::spike::{Spike, SpikeTrain};

    #[test]
    fn marks_wave_participants() {
        let mut train = SpikeTrain::default();
        train.push(Spike { channel: 0, within_trace_time_ms: 10.0, ..Default::default() });
        train.push(Spike { channel: 1, within_trace_time_ms: 15.0, ..Default::default() });
        train.push(Spike { channel: 2, within_trace_time_ms: 200.0, ..Default::default() });
        let report = activation_from_spikes("m.modat", &train, &ActivationOptions::default());
        assert_eq!(report.origin_channel, Some(0));
        assert!(report.cells[1].participated);
        assert!(!report.cells[2].participated);
    }
}