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
//! PDM Detector (`pdmdetector99`): spike detect + timestamp package export.
//! Distinct from Propagation Delay Map (PDM), which maps from timestamps.
//!
//! # Timestamp CSV styles
//!
//! - [`PdmTimestampCsvStyle::PdmDetector`] (default): package parity with toolkit
//!   `pdmdetector99.Timestampoutput` — `cluster_id=None`, `pre_ms=0`, `y0/y1=0`
//!   when waveforms are absent (reference omits meaningful y0/y1).
//! - [`PdmTimestampCsvStyle::RustFull`]: when a spike has a waveform snippet,
//!   `y0`/`y1`/`pre`/`post` come from waveform ends (burst-analysis).

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

use serde::{Deserialize, Serialize};

use crate::analysis::{run_analysis, AnalysisOptions, AnalysisReport, SpikeTrain};
use crate::error::{Med64Error, Result};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum PdmTimestampMode {
    /// One CSV with all channels (`Timestampoutput`).
    #[default]
    All,
    /// One CSV per channel (`*ineach`).
    Each,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum PdmTimestampVariant {
    /// `.modat` detector layout.
    #[default]
    Modat,
    /// `.dat` detector layout (same columns; stem tagging).
    Dat,
    /// Well-plate layout (same columns; well-oriented package).
    WellPlate,
}

/// Row formatting for PDM Detector timestamp CSV.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum PdmTimestampCsvStyle {
    /// Match PDM Detector export (default for package parity).
    #[default]
    PdmDetector,
    /// Prefer waveform window ends when present; otherwise zero y0/y1.
    RustFull,
}

#[derive(Debug, Clone)]
pub struct PdmDetectorOptions {
    pub analysis: AnalysisOptions,
    pub mode: PdmTimestampMode,
    pub variant: PdmTimestampVariant,
    /// Prefixed onto output filenames.
    pub name: String,
    pub csv_style: PdmTimestampCsvStyle,
}

impl Default for PdmDetectorOptions {
    fn default() -> Self {
        Self {
            analysis: AnalysisOptions { max_blocks: Some(10), ..AnalysisOptions::default() },
            mode: PdmTimestampMode::All,
            variant: PdmTimestampVariant::Modat,
            name: "Timestamp".into(),
            csv_style: PdmTimestampCsvStyle::PdmDetector,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PdmDetectorReport {
    pub path: PathBuf,
    pub spike_count: usize,
    pub outputs: Vec<PathBuf>,
}

/// Detect spikes for PDM Detector (stage 1).
pub fn run_pdm_detector(
    path: impl AsRef<Path>,
    options: &PdmDetectorOptions,
) -> Result<(AnalysisReport, SpikeTrain)> {
    let report = run_analysis(path.as_ref(), &options.analysis)?;
    let train = report.spikes.clone();
    Ok((report, train))
}

/// Write `Timestampoutput`-style package (all and/or each).
pub fn write_pdm_timestamp_package(
    report: &AnalysisReport,
    out_dir: impl AsRef<Path>,
    options: &PdmDetectorOptions,
) -> 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 mut outs = Vec::new();
    let tag = match options.variant {
        PdmTimestampVariant::Modat => "",
        PdmTimestampVariant::Dat => "_dat",
        PdmTimestampVariant::WellPlate => "_presto", // wire suffix for PRESTO exports
    };
    match options.mode {
        PdmTimestampMode::All => {
            let path = dir.join(format!("{}{tag}.csv", options.name));
            write_pdm_timestamp_csv(report, &path, None, options.csv_style)?;
            outs.push(path);
        }
        PdmTimestampMode::Each => {
            let by = report.spikes.by_channel();
            for &ch in by.keys() {
                let path = dir.join(format!("{}_ch{}{tag}.csv", options.name, ch + 1));
                write_pdm_timestamp_csv(report, &path, Some(ch), options.csv_style)?;
                outs.push(path);
            }
        }
    }
    let manifest = dir.join("pdm_detector_manifest.json");
    let body = serde_json::json!({
        "source": report.path.display().to_string(),
        "mode": format!("{:?}", options.mode),
        "variant": format!("{:?}", options.variant),
        "csv_style": format!("{:?}", options.csv_style),
        "spike_count": report.spikes.spikes.len(),
        "files": outs.iter().map(|p| p.display().to_string()).collect::<Vec<_>>(),
    });
    std::fs::write(&manifest, serde_json::to_string_pretty(&body).unwrap())
        .map_err(|source| Med64Error::WriteIo { path: manifest.clone(), source })?;
    outs.push(manifest);
    Ok(outs)
}

pub fn run_pdm_detector_package(
    path: impl AsRef<Path>,
    out_dir: impl AsRef<Path>,
    options: &PdmDetectorOptions,
) -> Result<PdmDetectorReport> {
    let path = path.as_ref();
    let (report, _) = run_pdm_detector(path, options)?;
    let outputs = write_pdm_timestamp_package(&report, out_dir, options)?;
    Ok(PdmDetectorReport {
        path: path.to_path_buf(),
        spike_count: report.spikes.spikes.len(),
        outputs,
    })
}

/// `Timestampoutput` column header (single line after metadata rows).
pub fn pdm_timestamp_data_header() -> &'static str {
    "channel,time_of_day,within_session_time,within_session_time_ms,within_trace_time_ms,cluster_id,trace_num,pre_ms,post_ms,y0_mV,y1_mV"
}

fn row_fields(
    spike: &crate::analysis::Spike,
    style: PdmTimestampCsvStyle,
) -> (String, f64, f64, f64, f64) {
    let has_wf = !spike.waveform_mv.is_empty();
    match style {
        PdmTimestampCsvStyle::PdmDetector => {
            // PdmDetectorOmit: cluster "None", pre=0; y0/y1 zero unless waveform retained.
            if has_wf {
                let y0 = spike.waveform_mv.first().copied().unwrap_or(0.0);
                let y1 = spike.waveform_mv.last().copied().unwrap_or(spike.peak_mv);
                let pre = spike
                    .waveform_times_ms
                    .first()
                    .map(|t| (spike.within_trace_time_ms - t).abs())
                    .unwrap_or(0.0);
                let post = spike
                    .waveform_times_ms
                    .last()
                    .map(|t| (t - spike.within_trace_time_ms).abs())
                    .unwrap_or(0.0);
                ("None".into(), pre, post, y0, y1)
            } else {
                ("None".into(), 0.0, 0.0, 0.0, 0.0)
            }
        }
        PdmTimestampCsvStyle::RustFull => {
            if has_wf {
                let y0 = spike.waveform_mv.first().copied().unwrap_or(0.0);
                let y1 = spike.waveform_mv.last().copied().unwrap_or(spike.peak_mv);
                let pre = spike.waveform_times_ms.first().copied().unwrap_or(0.0).abs();
                let post = spike.waveform_times_ms.last().copied().unwrap_or(0.0).abs();
                ("0".into(), pre, post, y0, y1)
            } else {
                ("0".into(), 1.0, 2.5, 0.0, spike.peak_mv)
            }
        }
    }
}

/// Write PDM Detector CSV matching `Timestampoutput` layout.
pub fn write_pdm_timestamp_csv(
    report: &AnalysisReport,
    path: impl AsRef<Path>,
    channel_filter: Option<usize>,
    style: PdmTimestampCsvStyle,
) -> Result<()> {
    let path = path.as_ref();
    let h = &report.header;
    let session =
        format!("{:04}/{:02}/{:02} {}", h.start_year, h.start_month, h.start_day, format_tod(h));
    let mut out = String::new();
    // Timestampoutput hardcodes format token `20071201`.
    out.push_str("File Format Version,20071201\n");
    out.push_str(&format!("Session Start Time,{session}\n"));
    out.push_str(&format!("Trace Duration (ms),{:.0}\n", h.real_trace_duration_ms));
    out.push('\n');
    out.push_str(pdm_timestamp_data_header());
    out.push('\n');

    let mut spikes: Vec<_> = report.spikes.spikes.iter().collect();
    spikes.sort_by(|a, b| {
        a.within_session_time_ms
            .partial_cmp(&b.within_session_time_ms)
            .unwrap()
            .then_with(|| a.channel.cmp(&b.channel))
    });
    for spike in spikes {
        if channel_filter.is_some_and(|ch| spike.channel != ch) {
            continue;
        }
        let (cluster, pre_ms, post_ms, y0, y1) = row_fields(spike, style);
        let wst_s = spike.within_session_time_ms / 1000.0;
        out.push_str(&format!(
            "{},{},{:.6},{:.3},{:.3},{},{},{:.3},{:.3},{:.6},{:.6}\n",
            spike.channel + 1,
            format_tod(h),
            wst_s,
            spike.within_session_time_ms,
            spike.within_trace_time_ms,
            cluster,
            spike.trace + 1,
            pre_ms,
            post_ms,
            y0,
            y1,
        ));
    }
    std::fs::write(path, out)
        .map_err(|source| Med64Error::WriteIo { path: path.to_path_buf(), source })
}

fn format_tod(h: &crate::header::Med64Header) -> String {
    format!(
        "{:02}:{:02}:{:02}.{:03}",
        h.start_hour(),
        h.start_minute(),
        h.start_second(),
        h.start_millisecond()
    )
}

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

    fn mini_report(with_wf: bool) -> AnalysisReport {
        let mut spikes = SpikeTrain::default();
        spikes.push(Spike {
            channel: 0,
            trace: 0,
            direction: SpikeDirection::Plus,
            peak_mv: -0.12,
            within_trace_time_ms: 10.0,
            within_session_time_ms: 10.0,
            waveform_mv: if with_wf { vec![-0.01, -0.12, -0.02] } else { Vec::new() },
            waveform_times_ms: if with_wf { vec![9.0, 10.0, 12.5] } else { Vec::new() },
            ..Default::default()
        });
        let header = HeaderBuilder::new().build();
        run_analysis_from_spikes("test.modat", header, spikes, &AnalysisOptions::default()).unwrap()
    }

    #[test]
    fn header_matches_expected_columns() {
        assert!(pdm_timestamp_data_header().contains("cluster_id"));
        assert!(pdm_timestamp_data_header().contains("pre_ms"));
        assert!(pdm_timestamp_data_header().contains("within_session_time,"));
    }

    #[test]
    fn pdm_row_format_without_waveform() {
        let report = mini_report(false);
        let dir = std::env::temp_dir().join(format!("med64-pdm-csv-{}", std::process::id()));
        let _ = std::fs::create_dir_all(&dir);
        let path = dir.join("ts.csv");
        write_pdm_timestamp_csv(&report, &path, None, PdmTimestampCsvStyle::PdmDetector).unwrap();
        let body = std::fs::read_to_string(&path).unwrap();
        let data = body.lines().find(|l| l.starts_with('1')).unwrap();
        let cols: Vec<_> = data.split(',').collect();
        assert_eq!(cols[5], "None", "cluster_id");
        assert_eq!(cols[7], "0.000", "pre_ms");
        assert_eq!(cols[9], "0.000000", "y0_mV");
        assert_eq!(cols[10], "0.000000", "y1_mV");
        let _ = std::fs::remove_dir_all(dir);
    }

    #[test]
    fn rust_full_uses_waveform_ends() {
        let report = mini_report(true);
        let dir = std::env::temp_dir().join(format!("med64-pdm-wf-{}", std::process::id()));
        let _ = std::fs::create_dir_all(&dir);
        let path = dir.join("ts.csv");
        write_pdm_timestamp_csv(&report, &path, None, PdmTimestampCsvStyle::RustFull).unwrap();
        let body = std::fs::read_to_string(&path).unwrap();
        let data = body.lines().find(|l| l.starts_with('1')).unwrap();
        let cols: Vec<_> = data.split(',').collect();
        assert_eq!(cols[9], "-0.010000", "y0 first sample");
        assert_eq!(cols[10], "-0.020000", "y1 last sample");
        let _ = std::fs::remove_dir_all(dir);
    }

    #[test]
    fn rust_full_without_waveform_uses_peak() {
        let report = mini_report(false);
        let dir = std::env::temp_dir().join(format!("med64-pdm-nowf-{}", std::process::id()));
        let _ = std::fs::create_dir_all(&dir);
        let path = dir.join("ts.csv");
        write_pdm_timestamp_csv(&report, &path, None, PdmTimestampCsvStyle::RustFull).unwrap();
        let body = std::fs::read_to_string(&path).unwrap();
        let data = body.lines().find(|l| l.starts_with('1')).unwrap();
        let cols: Vec<_> = data.split(',').collect();
        assert_eq!(cols[9], "0.000000", "y0");
        assert_eq!(cols[10], "-0.120000", "y1 peak_mv");
        let _ = std::fs::remove_dir_all(dir);
    }
}