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
//! Spike feature clustering (Clustering / connectivity).

use serde::{Deserialize, Serialize};

use crate::analysis::spike::SpikeTrain;

#[derive(Debug, Clone)]
pub struct ClusterOptions {
    pub k: usize,
    pub max_iters: usize,
    /// Feature: peak amplitude (always) + optional duration.
    pub use_duration: bool,
}

impl Default for ClusterOptions {
    fn default() -> Self {
        Self { k: 3, max_iters: 25, use_duration: true }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ClusterAssignment {
    pub spike_index: usize,
    pub channel: usize,
    pub cluster: usize,
    pub peak_mv: f64,
    pub duration_ms: f64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ClusterCentroid {
    pub cluster: usize,
    pub mean_peak_mv: f64,
    pub mean_duration_ms: f64,
    pub n_spikes: usize,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ClusterReport {
    pub assignments: Vec<ClusterAssignment>,
    pub centroids: Vec<ClusterCentroid>,
}

/// k-means on spike peak (± duration) features.
pub fn cluster_spikes(train: &SpikeTrain, options: &ClusterOptions) -> ClusterReport {
    let k = options.k.max(1);
    if train.spikes.is_empty() {
        return ClusterReport { assignments: Vec::new(), centroids: Vec::new() };
    }

    let features: Vec<[f64; 2]> = train
        .spikes
        .iter()
        .map(|s| [s.peak_mv, if options.use_duration { s.duration_ms } else { 0.0 }])
        .collect();

    let mut centroids: Vec<[f64; 2]> = (0..k).map(|i| features[i * features.len() / k]).collect();
    let mut labels = vec![0usize; features.len()];

    for _ in 0..options.max_iters {
        for (i, feat) in features.iter().enumerate() {
            let mut best = 0usize;
            let mut best_d = f64::INFINITY;
            for (c, cent) in centroids.iter().enumerate() {
                let d = (feat[0] - cent[0]).powi(2) + (feat[1] - cent[1]).powi(2);
                if d < best_d {
                    best_d = d;
                    best = c;
                }
            }
            labels[i] = best;
        }
        let mut sums = vec![[0.0_f64; 2]; k];
        let mut counts = vec![0usize; k];
        for (i, feat) in features.iter().enumerate() {
            let c = labels[i];
            sums[c][0] += feat[0];
            sums[c][1] += feat[1];
            counts[c] += 1;
        }
        for c in 0..k {
            if counts[c] > 0 {
                centroids[c][0] = sums[c][0] / counts[c] as f64;
                centroids[c][1] = sums[c][1] / counts[c] as f64;
            }
        }
    }

    let assignments: Vec<ClusterAssignment> = train
        .spikes
        .iter()
        .enumerate()
        .map(|(i, s)| ClusterAssignment {
            spike_index: i,
            channel: s.channel,
            cluster: labels[i],
            peak_mv: s.peak_mv,
            duration_ms: s.duration_ms,
        })
        .collect();

    let mut centroids_out = Vec::new();
    for c in 0..k {
        let members: Vec<_> = assignments.iter().filter(|a| a.cluster == c).collect();
        let n = members.len();
        centroids_out.push(ClusterCentroid {
            cluster: c,
            mean_peak_mv: if n > 0 {
                members.iter().map(|m| m.peak_mv).sum::<f64>() / n as f64
            } else {
                0.0
            },
            mean_duration_ms: if n > 0 {
                members.iter().map(|m| m.duration_ms).sum::<f64>() / n as f64
            } else {
                0.0
            },
            n_spikes: n,
        });
    }

    ClusterReport { assignments, centroids: centroids_out }
}

/// Write clustering package: `clusters.csv`, `centroids.csv`, `cluster_scatter.html`.
pub fn write_cluster_package(
    report: &ClusterReport,
    _train: &SpikeTrain,
    out_dir: impl AsRef<std::path::Path>,
) -> crate::error::Result<Vec<std::path::PathBuf>> {
    use crate::error::Med64Error;
    let dir = out_dir.as_ref();
    std::fs::create_dir_all(dir)
        .map_err(|source| Med64Error::WriteIo { path: dir.to_path_buf(), source })?;
    let mut outs = Vec::new();

    let clusters_csv = dir.join("clusters.csv");
    {
        let mut w = String::from("spike_index,channel,cluster,peak_mv,duration_ms\n");
        for a in &report.assignments {
            w.push_str(&format!(
                "{},{},{},{:.6},{:.6}\n",
                a.spike_index,
                a.channel + 1,
                a.cluster,
                a.peak_mv,
                a.duration_ms
            ));
        }
        std::fs::write(&clusters_csv, w)
            .map_err(|source| Med64Error::WriteIo { path: clusters_csv.clone(), source })?;
    }
    outs.push(clusters_csv);

    let centroids_csv = dir.join("centroids.csv");
    {
        let mut w = String::from("cluster,mean_peak_mv,mean_duration_ms,n_spikes\n");
        for c in &report.centroids {
            w.push_str(&format!(
                "{},{:.6},{:.6},{}\n",
                c.cluster, c.mean_peak_mv, c.mean_duration_ms, c.n_spikes
            ));
        }
        std::fs::write(&centroids_csv, w)
            .map_err(|source| Med64Error::WriteIo { path: centroids_csv.clone(), source })?;
    }
    outs.push(centroids_csv);

    let max_peak = report.assignments.iter().map(|a| a.peak_mv.abs()).fold(1e-9_f64, f64::max);
    let max_dur = report.assignments.iter().map(|a| a.duration_ms).fold(1e-9_f64, f64::max);
    let mut circles = String::new();
    for a in report.assignments.iter().take(4000) {
        let x = 40.0 + (a.peak_mv.abs() / max_peak) * 320.0;
        let y = 340.0 - (a.duration_ms / max_dur) * 300.0;
        let hue = (a.cluster * 67) % 360;
        circles.push_str(&format!(
            "<circle cx=\"{x:.1}\" cy=\"{y:.1}\" r=\"3\" fill=\"hsl({hue} 65% 45%)\" opacity=\"0.7\"/>"
        ));
    }
    let scatter = dir.join("cluster_scatter.html");
    let html = format!(
        r#"<!DOCTYPE html>
<html><head><meta charset="utf-8"><title>Spike clusters</title>
<style>body{{font-family:system-ui;margin:1rem}}</style></head><body>
<h1>Spike feature clusters</h1>
<p>{} spikes · {} clusters (peak vs duration)</p>
<svg width="400" height="380" viewBox="0 0 400 380" style='background:#fff;border:1px solid #e2e8f0'>
<text x="200" y="18" text-anchor="middle" font-size="12" fill='#64748b'>|peak| (mV) →</text>
<text x="12" y="200" font-size="12" fill='#64748b' transform="rotate(-90 12 200)">duration (ms)</text>
{circles}
</svg>
</body></html>"#,
        report.assignments.len(),
        report.centroids.len(),
        circles = circles
    );
    std::fs::write(&scatter, html)
        .map_err(|source| Med64Error::WriteIo { path: scatter.clone(), source })?;
    outs.push(scatter);
    Ok(outs)
}

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

    #[test]
    fn separates_amplitudes() {
        let mut train = SpikeTrain::default();
        for _ in 0..10 {
            train.push(Spike { peak_mv: 0.2, duration_ms: 1.0, ..Default::default() });
            train.push(Spike { peak_mv: 2.0, duration_ms: 1.0, ..Default::default() });
        }
        let report = cluster_spikes(&train, &ClusterOptions { k: 2, ..Default::default() });
        assert_eq!(report.centroids.len(), 2);
        assert!(report.centroids.iter().any(|c| c.n_spikes > 0));
    }

    #[test]
    fn cluster_package_writes() {
        let mut train = SpikeTrain::default();
        for i in 0..20 {
            train.push(Spike {
                peak_mv: if i < 10 { 0.2 } else { 2.0 },
                duration_ms: 1.0 + (i as f64) * 0.01,
                channel: i % 4,
                ..Default::default()
            });
        }
        let report = cluster_spikes(&train, &ClusterOptions { k: 2, ..Default::default() });
        let dir = std::env::temp_dir().join("med64_cluster_pkg_test");
        let _ = std::fs::remove_dir_all(&dir);
        let outs = write_cluster_package(&report, &train, &dir).unwrap();
        assert_eq!(outs.len(), 3);
        assert!(dir.join("clusters.csv").is_file());
        assert!(dir.join("cluster_scatter.html").is_file());
    }
}