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
use std::io::Write;
use std::path::Path;

use crate::analysis::{
    format_spike_csv_row, spike_timestamp_csv_header, AnalysisReport, SpikeTrain,
};
use crate::error::Result;
use crate::header::Med64Header;

use super::util::{create_writer, io};

pub fn write_spike_timestamps_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    write_spike_timestamps_csv_from_train(&report.header, &report.spikes, path)
}

/// Write spike timestamp CSV for an arbitrary [`SpikeTrain`] subset (e.g. one trace).
pub fn write_spike_timestamps_csv_from_train(
    header: &Med64Header,
    train: &SpikeTrain,
    path: impl AsRef<Path>,
) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    write!(writer, "{}", crate::analysis::spike_timestamp_preamble(header)).map_err(io(path))?;
    writeln!(writer).map_err(io(path))?;
    writeln!(writer, "{}", spike_timestamp_csv_header()).map_err(io(path))?;
    for spike in &train.spikes {
        writeln!(writer, "{}", format_spike_csv_row(header, spike)).map_err(io(path))?;
    }
    writer.flush().map_err(io(path))?;
    Ok(())
}

pub fn write_single_burst_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    // SingleChannelBurstExporter header (comma-separated).
    writeln!(
        writer,
        "trace#,ch,start time (ms),interburst interval (ms),spikes in a burst (spikes),duration (ms)"
    )
    .map_err(io(path))?;
    for burst in &report.single_bursts {
        let ibi = if burst.interburst_interval_ms > 0.0 {
            format!("{:.6}", burst.interburst_interval_ms)
        } else {
            String::new()
        };
        writeln!(
            writer,
            "{},{},{:.6},{},{},{:.6}",
            burst.trace + 1,
            burst.channel + 1,
            burst.start_ms,
            ibi,
            burst.num_spikes,
            burst.duration_ms
        )
        .map_err(io(path))?;
    }
    Ok(())
}

pub fn write_multi_burst_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    // MultiChannelBurstExporter header.
    writeln!(
        writer,
        "trace#,start time (ms),interburst interval (ms),peak (spikes/s),spikes in a burst (spikes),duration (ms)"
    )
    .map_err(io(path))?;
    for (i, burst) in report.multi_bursts.iter().enumerate() {
        let ibi = if i == 0 {
            String::new()
        } else {
            let prev = &report.multi_bursts[i - 1];
            format!("{:.6}", burst.start_ms - prev.end_ms)
        };
        writeln!(
            writer,
            "{},{:.6},{},{:.6},{},{:.6}",
            burst.trace + 1,
            burst.start_ms,
            ibi,
            burst.peak_rate_hz,
            burst.num_spikes,
            burst.end_ms - burst.start_ms
        )
        .map_err(io(path))?;
    }
    Ok(())
}

pub fn write_asdr_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    // MultiChannelBurstASDRExporter header.
    writeln!(writer, "time (ms),spikes/s,smoothing (spikes/s)").map_err(io(path))?;
    for point in &report.asdr.points {
        writeln!(writer, "{:.6},{:.6},{:.6}", point.time_ms, point.rate_hz, point.smoothed_hz)
            .map_err(io(path))?;
    }
    Ok(())
}

pub fn write_intra_burst_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    // MultiChannelBurstIntraBurstSpikeExporter header + multi-burst windows
    // ([start_ms, end_ms) via extractByTopTimeEndNotEqual).
    writeln!(writer, "trace#,burst#,ch#,time (ms),mV").map_err(io(path))?;
    for (burst_idx, burst) in report.multi_bursts.iter().enumerate() {
        let mut in_window: Vec<_> = report
            .spikes
            .spikes
            .iter()
            .filter(|s| {
                s.within_trace_time_ms >= burst.start_ms && s.within_trace_time_ms < burst.end_ms
            })
            .collect();
        in_window.sort_by(|a, b| {
            a.channel.cmp(&b.channel).then(
                a.within_trace_time_ms
                    .partial_cmp(&b.within_trace_time_ms)
                    .unwrap_or(std::cmp::Ordering::Equal),
            )
        });
        for spike in in_window {
            writeln!(
                writer,
                "{},{},{},{:.6},{:.6}",
                spike.trace + 1,
                burst_idx + 1,
                spike.channel + 1,
                spike.within_trace_time_ms,
                spike.peak_mv
            )
            .map_err(io(path))?;
        }
    }
    Ok(())
}

pub fn write_frequency_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    writeln!(writer, "channel,start_ms,end_ms,spike_count,rate_hz").map_err(io(path))?;
    for bin in &report.frequency_bins {
        writeln!(
            writer,
            "{},{:.3},{:.3},{},{:.6}",
            bin.channel + 1,
            bin.start_ms,
            bin.end_ms,
            bin.spike_count,
            bin.rate_hz
        )
        .map_err(io(path))?;
    }
    Ok(())
}

pub fn write_filtered_raw_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    writeln!(writer, "time_ms,channel,millivolts").map_err(io(path))?;
    if !report.filtered_by_channel.is_empty() {
        let interval = report.header.interval_ms();
        for (&channel, samples) in &report.filtered_by_channel {
            for (i, &mv) in samples.iter().enumerate() {
                writeln!(writer, "{:.4},{},{:.8}", i as f64 * interval, channel + 1, mv)
                    .map_err(io(path))?;
            }
        }
    } else {
        for sample in &report.filtered_preview {
            writeln!(
                writer,
                "{:.4},{},{:.8}",
                sample.time_ms,
                sample.channel + 1,
                sample.millivolts
            )
            .map_err(io(path))?;
        }
    }
    Ok(())
}

/// Spike timestamps plus waveform samples (`SpikeTimeStampPlusSpikes`).
pub fn write_spike_timestamps_plus_waveforms_csv(
    report: &AnalysisReport,
    path: impl AsRef<Path>,
) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    write!(writer, "{}", crate::analysis::spike_timestamp_preamble(&report.header))
        .map_err(io(path))?;
    writeln!(writer).map_err(io(path))?;
    writeln!(writer, "{},waveform_mv", spike_timestamp_csv_header()).map_err(io(path))?;
    for spike in &report.spikes.spikes {
        let wave =
            spike.waveform_mv.iter().map(|v| format!("{v:.6}")).collect::<Vec<_>>().join(" ");
        writeln!(writer, "{},\"{}\"", format_spike_csv_row(&report.header, spike), wave)
            .map_err(io(path))?;
    }
    Ok(())
}

pub fn write_average_waveforms_csv(
    waveforms: &[crate::analysis::AverageWaveform],
    path: impl AsRef<Path>,
) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    writeln!(writer, "channel,direction,n_spikes,sample_index,mean_mv").map_err(io(path))?;
    for avg in waveforms {
        let dir = match avg.direction {
            crate::analysis::SpikeDirection::Plus => "plus",
            crate::analysis::SpikeDirection::Minus => "minus",
        };
        for (i, &mv) in avg.mean_mv.iter().enumerate() {
            writeln!(writer, "{},{},{},{},{:.8}", avg.channel + 1, dir, avg.n_spikes, i, mv)
                .map_err(io(path))?;
        }
    }
    Ok(())
}

#[cfg(feature = "histograms")]
pub fn write_histogram_csv(
    edges: &[f64],
    counts: &[u64],
    path: impl AsRef<Path>,
    edge_name: &str,
) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    writeln!(writer, "{edge_name},count").map_err(io(path))?;
    for (i, count) in counts.iter().enumerate() {
        let edge = edges.get(i).copied().unwrap_or(0.0);
        writeln!(writer, "{edge:.6},{count}").map_err(io(path))?;
    }
    Ok(())
}

#[cfg(feature = "correlation")]
pub fn write_correlogram_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    // BurstOnsetTimeCrossCorrelogramExporter header.
    writeln!(writer, "start time (ms),end time (ms),spikes").map_err(io(path))?;
    let half = report
        .correlogram
        .lag_ms
        .windows(2)
        .map(|w| (w[1] - w[0]).abs() / 2.0)
        .next()
        .unwrap_or(2.5);
    for (lag, count) in report.correlogram.lag_ms.iter().zip(report.correlogram.counts.iter()) {
        writeln!(writer, "{:.3},{:.3},{}", lag - half, lag + half, count).map_err(io(path))?;
    }
    Ok(())
}

#[cfg(feature = "correlation")]
pub fn write_synchrony_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    // SynchronyIndexExporter: ch#,ch#,synchrony,total,SI
    writeln!(writer, "ch#,ch#,synchrony,total,SI").map_err(io(path))?;
    for row in &report.synchrony {
        writeln!(
            writer,
            "{},{},{},{},{:.6}",
            row.channel_a + 1,
            row.channel_b + 1,
            row.coincident_bursts,
            row.bursts_a,
            row.synchrony_index
        )
        .map_err(io(path))?;
    }
    Ok(())
}

pub fn write_autocorr_csv(
    report: &crate::analysis::AutocorrReport,
    path: impl AsRef<Path>,
) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    write!(writer, "lag_ms,total").map_err(io(path))?;
    for ch in &report.channels {
        write!(writer, ",ch{}", ch.channel + 1).map_err(io(path))?;
    }
    writeln!(writer).map_err(io(path))?;
    for (i, &lag) in report.lag_ms.iter().enumerate() {
        write!(writer, "{:.3},{}", lag, report.total_counts.get(i).copied().unwrap_or(0))
            .map_err(io(path))?;
        for ch in &report.channels {
            write!(writer, ",{}", ch.counts.get(i).copied().unwrap_or(0)).map_err(io(path))?;
        }
        writeln!(writer).map_err(io(path))?;
    }
    Ok(())
}

pub fn write_raster_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    writeln!(writer, "channel,trace,time_ms,peak_mv").map_err(io(path))?;
    for p in &report.raster.points {
        writeln!(writer, "{},{},{:.3},{:.6}", p.channel + 1, p.trace + 1, p.time_ms, p.peak_mv)
            .map_err(io(path))?;
    }
    Ok(())
}

pub fn write_burst_profile_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut writer = create_writer(path)?;
    writeln!(writer, "lag_ms,mean_rate_hz,n_bursts").map_err(io(path))?;
    for p in &report.burst_profile.points {
        writeln!(writer, "{:.3},{:.6},{}", p.lag_ms, p.mean_rate_hz, p.n_bursts)
            .map_err(io(path))?;
    }
    Ok(())
}