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 detector variant 1 — multi-range spike-frequency summary (`spikedetectorvariant1`).

use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::analysis::spike::SpikeTrain;
use crate::analysis::{run_analysis, AnalysisReport};
use crate::error::{Med64Error, Result};
use crate::toolkit::spike_detector::{
    analysis_options_from, compute_threshold_table, SpikeDetectorOptions, SpikePolarity,
};

/// One analysis window (start + duration), matching Toolkit range rows.
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct TimeRangeMs {
    pub start_ms: f64,
    pub duration_ms: f64,
}

impl TimeRangeMs {
    pub fn end_ms(self) -> f64 {
        self.start_ms + self.duration_ms
    }
}

#[derive(Debug, Clone)]
pub struct SpikeFrequencyOptions {
    /// Up to 8 ranges (Toolkit UI).
    pub ranges: Vec<TimeRangeMs>,
    /// Active-channel criterion in spikes/s (default 1).
    pub active_criteria_hz: f64,
    pub spike: SpikeDetectorOptions,
}

impl Default for SpikeFrequencyOptions {
    fn default() -> Self {
        Self {
            ranges: (0..8)
                .map(|i| TimeRangeMs { start_ms: i as f64 * 30_000.0, duration_ms: 30_000.0 })
                .collect(),
            active_criteria_hz: 1.0,
            spike: SpikeDetectorOptions {
                polarity: SpikePolarity::MinusOnly,
                ..SpikeDetectorOptions::toolkit_default()
            },
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RangeFrequencyStats {
    pub range_index: usize,
    pub start_ms: f64,
    pub end_ms: f64,
    pub mean_hz: f64,
    pub sd_hz: f64,
    pub median_hz: f64,
    pub active_channels: usize,
    pub total_spikes: usize,
    /// Mean pairwise synchrony of active channels in-range (0–1).
    #[serde(default)]
    pub synchrony: f64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SpikeFrequencyReport {
    pub path: PathBuf,
    pub spike_count: usize,
    pub ranges: Vec<RangeFrequencyStats>,
    pub active_criteria_hz: f64,
}

/// Run Toolkit-style spike detect then summarize rates over each time range.
pub fn run_spike_frequency(
    path: impl AsRef<Path>,
    options: &SpikeFrequencyOptions,
) -> Result<SpikeFrequencyReport> {
    let path = path.as_ref();
    let thresholds = compute_threshold_table(path, &options.spike)?;
    let analysis_opts = analysis_options_from(&options.spike, &thresholds);
    let analysis = run_analysis(path, &analysis_opts)?;
    Ok(spike_frequency_from_analysis(&analysis, options))
}

pub fn spike_frequency_from_analysis(
    analysis: &AnalysisReport,
    options: &SpikeFrequencyOptions,
) -> SpikeFrequencyReport {
    let train = &analysis.spikes;
    let n_ch = analysis.header.active_channel_indices().len().max(1);
    let ranges: Vec<RangeFrequencyStats> = options
        .ranges
        .iter()
        .enumerate()
        .take(8)
        .map(|(i, r)| range_stats(train, *r, i, n_ch, options.active_criteria_hz))
        .collect();
    SpikeFrequencyReport {
        path: analysis.path.clone(),
        spike_count: train.len(),
        ranges,
        active_criteria_hz: options.active_criteria_hz,
    }
}

fn range_stats(
    train: &SpikeTrain,
    range: TimeRangeMs,
    range_index: usize,
    n_channels: usize,
    criteria_hz: f64,
) -> RangeFrequencyStats {
    let end = range.end_ms();
    let dur_s = (range.duration_ms / 1000.0).max(1e-9);
    let mut per_ch = vec![0usize; n_channels.max(64)];
    let mut total = 0usize;
    for sp in &train.spikes {
        let t = sp.within_trace_time_ms;
        if t >= range.start_ms && t < end {
            total += 1;
            if sp.channel < per_ch.len() {
                per_ch[sp.channel] += 1;
            }
        }
    }
    let rates: Vec<f64> = per_ch.iter().take(n_channels).map(|&c| c as f64 / dur_s).collect();
    let mean = if rates.is_empty() { 0.0 } else { rates.iter().sum::<f64>() / rates.len() as f64 };
    let var = if rates.len() < 2 {
        0.0
    } else {
        rates.iter().map(|r| (r - mean).powi(2)).sum::<f64>() / rates.len() as f64
    };
    let mut sorted = rates.clone();
    sorted.sort_by(|a, b| a.partial_cmp(b).unwrap());
    let median = median_sorted(&sorted);
    let active = rates.iter().filter(|&&r| r >= criteria_hz).count();
    let synchrony = range_synchrony(train, range.start_ms, end, criteria_hz, &rates);
    RangeFrequencyStats {
        range_index,
        start_ms: range.start_ms,
        end_ms: end,
        mean_hz: mean,
        sd_hz: var.sqrt(),
        median_hz: median,
        active_channels: active,
        total_spikes: total,
        synchrony,
    }
}

fn range_synchrony(
    train: &SpikeTrain,
    start_ms: f64,
    end_ms: f64,
    criteria_hz: f64,
    rates: &[f64],
) -> f64 {
    let active: Vec<usize> =
        rates.iter().enumerate().filter(|(_, &r)| r >= criteria_hz).map(|(ch, _)| ch).collect();
    if active.len() < 2 {
        return 0.0;
    }
    let window = 5.0;
    let mut times: Vec<Vec<f64>> = active
        .iter()
        .map(|&ch| {
            train
                .spikes
                .iter()
                .filter(|s| {
                    s.channel == ch
                        && s.within_trace_time_ms >= start_ms
                        && s.within_trace_time_ms < end_ms
                })
                .map(|s| s.within_trace_time_ms)
                .collect()
        })
        .collect();
    for t in &mut times {
        t.sort_by(|a, b| a.partial_cmp(b).unwrap());
    }
    let mut sum = 0.0;
    let mut n = 0usize;
    for i in 0..times.len() {
        for j in (i + 1)..times.len() {
            if times[i].is_empty() {
                continue;
            }
            let mut coin = 0usize;
            for &ta in &times[i] {
                if times[j].iter().any(|&tb| (tb - ta).abs() <= window) {
                    coin += 1;
                }
            }
            sum += coin as f64 / times[i].len() as f64;
            n += 1;
        }
    }
    if n == 0 {
        0.0
    } else {
        sum / n as f64
    }
}

fn median_sorted(sorted: &[f64]) -> f64 {
    if sorted.is_empty() {
        return 0.0;
    }
    let n = sorted.len();
    if n % 2 == 0 {
        (sorted[n / 2 - 1] + sorted[n / 2]) / 2.0
    } else {
        sorted[n / 2]
    }
}

/// Tab-separated Toolkit-style frequency table.
pub fn write_spike_frequency_tsv(
    report: &SpikeFrequencyReport,
    path: impl AsRef<Path>,
) -> Result<()> {
    let path = path.as_ref();
    let mut out = String::new();
    out.push_str("Range #");
    for r in &report.ranges {
        out.push('\t');
        out.push_str(&(r.range_index + 1).to_string());
    }
    out.push('\n');
    write_row(&mut out, "Start (ms)", report.ranges.iter().map(|r| r.start_ms));
    write_row(&mut out, "End (ms)", report.ranges.iter().map(|r| r.end_ms));
    write_row(&mut out, "Mean", report.ranges.iter().map(|r| r.mean_hz));
    write_row(&mut out, "SD", report.ranges.iter().map(|r| r.sd_hz));
    write_row(&mut out, "Median", report.ranges.iter().map(|r| r.median_hz));
    out.push_str("#Active ch");
    for r in &report.ranges {
        out.push('\t');
        out.push_str(&r.active_channels.to_string());
    }
    out.push('\n');
    out.push_str("Total spikes");
    for r in &report.ranges {
        out.push('\t');
        out.push_str(&r.total_spikes.to_string());
    }
    out.push('\n');
    write_row(&mut out, "Synchrony", report.ranges.iter().map(|r| r.synchrony));
    out.push_str(&format!(
        "Filename\t{}\nActive channel criteria\t{:.6}\nSpike count\t{}\n",
        report.path.display(),
        report.active_criteria_hz,
        report.spike_count
    ));
    std::fs::write(path, out)
        .map_err(|source| Med64Error::WriteIo { path: path.to_path_buf(), source })
}

fn write_row(out: &mut String, label: &str, values: impl Iterator<Item = f64>) {
    out.push_str(label);
    for v in values {
        out.push('\t');
        out.push_str(&format!("{v:.6}"));
    }
    out.push('\n');
}

pub fn write_spike_frequency_package(
    report: &SpikeFrequencyReport,
    out_dir: impl AsRef<Path>,
) -> Result<Vec<PathBuf>> {
    let dir = out_dir.as_ref();
    std::fs::create_dir_all(dir)
        .map_err(|source| Med64Error::WriteIo { path: dir.to_path_buf(), source })?;
    let tsv = dir.join("spike_frequency.tsv");
    write_spike_frequency_tsv(report, &tsv)?;
    let csv = dir.join("spike_frequency.csv");
    let mut w = String::from(
        "range,start_ms,end_ms,mean_hz,sd_hz,median_hz,active_channels,total_spikes,synchrony\n",
    );
    for r in &report.ranges {
        w.push_str(&format!(
            "{},{:.3},{:.3},{:.6},{:.6},{:.6},{},{},{:.6}\n",
            r.range_index + 1,
            r.start_ms,
            r.end_ms,
            r.mean_hz,
            r.sd_hz,
            r.median_hz,
            r.active_channels,
            r.total_spikes,
            r.synchrony
        ));
    }
    std::fs::write(&csv, w).map_err(|source| Med64Error::WriteIo { path: csv.clone(), source })?;
    Ok(vec![tsv, csv])
}

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

    #[test]
    fn package_writes_tsv_and_csv() {
        let report = SpikeFrequencyReport {
            path: PathBuf::from("t.modat"),
            spike_count: 10,
            active_criteria_hz: 1.0,
            ranges: vec![RangeFrequencyStats {
                range_index: 0,
                start_ms: 0.0,
                end_ms: 1000.0,
                mean_hz: 2.5,
                sd_hz: 0.1,
                median_hz: 2.4,
                active_channels: 3,
                total_spikes: 10,
                synchrony: 0.0,
            }],
        };
        let dir = std::env::temp_dir().join(format!("med64-sf-{}", std::process::id()));
        let outs = write_spike_frequency_package(&report, &dir).unwrap();
        assert_eq!(outs.len(), 2);
        let tsv = std::fs::read_to_string(&outs[0]).unwrap();
        assert!(tsv.contains("Mean"));
        let _ = std::fs::remove_dir_all(dir);
    }
}