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
//! Average spike waveforms and spike-detector heatmap helpers.

use serde::{Deserialize, Serialize};

use crate::analysis::spike::{SpikeDirection, SpikeTrain};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AverageWaveform {
    pub channel: usize,
    pub direction: SpikeDirection,
    pub n_spikes: usize,
    pub times_ms: Vec<f64>,
    pub mean_mv: Vec<f64>,
}

/// Mean waveform per channel (and optionally direction), aligned at peak index center.
pub fn average_spike_waveforms(train: &SpikeTrain, by_direction: bool) -> Vec<AverageWaveform> {
    #[derive(Hash, Eq, PartialEq)]
    struct Key {
        channel: usize,
        direction: u8,
    }
    let mut groups: std::collections::HashMap<Key, Vec<&[f64]>> = std::collections::HashMap::new();
    for spike in &train.spikes {
        if spike.waveform_mv.is_empty() {
            continue;
        }
        let dir = if by_direction {
            match spike.direction {
                SpikeDirection::Plus => 1,
                SpikeDirection::Minus => 2,
            }
        } else {
            0
        };
        groups
            .entry(Key { channel: spike.channel, direction: dir })
            .or_default()
            .push(&spike.waveform_mv);
    }

    let mut out = Vec::new();
    for (key, waves) in groups {
        let width = waves.iter().map(|w| w.len()).max().unwrap_or(0);
        if width == 0 {
            continue;
        }
        let mut sum = vec![0.0_f64; width];
        let mut counts = vec![0usize; width];
        for w in &waves {
            // Align peaks at center of each snippet when lengths differ: use left-pad shorter.
            let offset = (width - w.len()) / 2;
            for (i, &v) in w.iter().enumerate() {
                sum[offset + i] += v;
                counts[offset + i] += 1;
            }
        }
        let mean: Vec<f64> = sum
            .iter()
            .zip(counts.iter())
            .map(|(&s, &c)| if c > 0 { s / c as f64 } else { 0.0 })
            .collect();
        let times: Vec<f64> = (0..width).map(|i| i as f64).collect();
        let direction = match key.direction {
            2 => SpikeDirection::Minus,
            _ => SpikeDirection::Plus,
        };
        out.push(AverageWaveform {
            channel: key.channel,
            direction,
            n_spikes: waves.len(),
            times_ms: times,
            mean_mv: mean,
        });
    }
    out.sort_by(|a, b| {
        a.channel.cmp(&b.channel).then_with(|| {
            (a.direction == SpikeDirection::Minus).cmp(&(b.direction == SpikeDirection::Minus))
        })
    });
    out
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HeatmapCell {
    pub channel: usize,
    pub row: usize,
    pub col: usize,
    pub spike_count: usize,
    pub mean_rate_hz: f64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SpikeHeatmap {
    pub cells: Vec<HeatmapCell>,
    pub max_count: usize,
}

/// Channel spike-count heatmap on an electrode grid (spike-detector style).
pub fn spike_heatmap(
    train: &SpikeTrain,
    duration_sec: f64,
    grid_rows: usize,
    grid_cols: usize,
) -> SpikeHeatmap {
    let mut counts = std::collections::BTreeMap::<usize, usize>::new();
    for spike in &train.spikes {
        *counts.entry(spike.channel).or_default() += 1;
    }
    let n = grid_rows * grid_cols;
    let mut cells = Vec::new();
    let mut max_count = 0usize;
    for ch in 0..n {
        let count = counts.get(&ch).copied().unwrap_or(0);
        max_count = max_count.max(count);
        let rate = if duration_sec > 0.0 { count as f64 / duration_sec } else { 0.0 };
        cells.push(HeatmapCell {
            channel: ch,
            row: ch / grid_cols,
            col: ch % grid_cols,
            spike_count: count,
            mean_rate_hz: rate,
        });
    }
    SpikeHeatmap { cells, max_count }
}

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

    #[test]
    fn averages_aligned_snippets() {
        let mut train = SpikeTrain::default();
        train.push(Spike { channel: 0, waveform_mv: vec![0.0, 1.0, 0.0], ..Default::default() });
        train.push(Spike { channel: 0, waveform_mv: vec![0.0, 3.0, 0.0], ..Default::default() });
        let avg = average_spike_waveforms(&train, false);
        assert_eq!(avg.len(), 1);
        assert!((avg[0].mean_mv[1] - 2.0).abs() < 1e-9);
    }
}