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
//! Voltage Chart (`wa99`) waveform export pack: Shorts / Doubles / CSV / + `.hdr`.

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

use serde::{Deserialize, Serialize};

use crate::analysis::{run_analysis, AnalysisOptions, AnalysisReport};
use crate::error::{Med64Error, Result};
use crate::export_waveform::write_filtered_i16_binary;
use crate::header::Med64Header;
use crate::recording::Recording;
use crate::toolkit::fbo::write_filtered_mobius_modat;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum DownsampleMode {
    #[default]
    None,
    Decimate,
    Average,
    Median,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum VoltageChartFormat {
    Mobius,
    Ascii,
    Shorts,
    Doubles,
}

/// ExportSetting `filtertype`: 0 raw / 1 filtered / 2 downsampled.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum VoltageFilterType {
    Raw = 0,
    #[default]
    Filtered = 1,
    Downsampled = 2,
}

/// `.hdr` layout: modat includes Session Start; dat omits it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub enum VoltageHdrStyle {
    #[default]
    Modat,
    Dat,
}

#[derive(Debug, Clone)]
pub struct VoltageChartOptions {
    pub max_blocks: Option<usize>,
    pub highpass_hz: Option<f64>,
    pub lowpass_hz: Option<f64>,
    /// Sample index window (inclusive start, exclusive end). `None` = all.
    pub from_sample: Option<usize>,
    pub to_sample: Option<usize>,
    pub downsample: usize,
    pub downsample_mode: DownsampleMode,
    pub formats: Vec<VoltageChartFormat>,
    pub name: String,
    /// Retain filtered traces for export.
    pub use_filtered: bool,
    /// CSVexport charset MS932 (ASCII rows are byte-identical).
    pub csv_ms932: bool,
    /// Optional time window in ms (converted using header interval).
    pub from_ms: Option<f64>,
    pub to_ms: Option<f64>,
    pub filter_type: VoltageFilterType,
    pub hdr_style: VoltageHdrStyle,
}

impl Default for VoltageChartOptions {
    fn default() -> Self {
        Self {
            max_blocks: Some(5),
            highpass_hz: Some(100.0),
            lowpass_hz: None,
            from_sample: None,
            to_sample: None,
            downsample: 1,
            downsample_mode: DownsampleMode::None,
            formats: vec![
                VoltageChartFormat::Shorts,
                VoltageChartFormat::Doubles,
                VoltageChartFormat::Ascii,
                VoltageChartFormat::Mobius,
            ],
            name: "voltage_chart".into(),
            use_filtered: true,
            csv_ms932: true,
            from_ms: None,
            to_ms: None,
            filter_type: VoltageFilterType::Filtered,
            hdr_style: VoltageHdrStyle::Modat,
        }
    }
}

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

pub fn run_voltage_chart_package(
    path: impl AsRef<Path>,
    out_dir: impl AsRef<Path>,
    options: &VoltageChartOptions,
) -> Result<VoltageChartPackageReport> {
    let path = path.as_ref();
    let mut analysis_opts = AnalysisOptions {
        max_blocks: options.max_blocks,
        highpass_hz: options.highpass_hz,
        lowpass_hz: options.lowpass_hz,
        retain_filtered: true,
        ..AnalysisOptions::default()
    };
    if analysis_opts.highpass_hz.is_none()
        && options.use_filtered
        && !matches!(options.filter_type, VoltageFilterType::Raw)
    {
        analysis_opts.highpass_hz = Some(100.0);
    }
    if matches!(options.filter_type, VoltageFilterType::Raw) {
        analysis_opts.highpass_hz = None;
        analysis_opts.lowpass_hz = None;
    }
    let mut report = run_analysis(path, &analysis_opts)?;
    if matches!(options.filter_type, VoltageFilterType::Raw) {
        report.filtered_by_channel = load_raw_by_channel(path, options.max_blocks)?;
    }
    let mut options = options.clone();
    let interval = report.header.interval_ms();
    if options.from_sample.is_none() {
        if let Some(ms) = options.from_ms {
            options.from_sample = Some((ms / interval).floor() as usize);
        }
    }
    if options.to_sample.is_none() {
        if let Some(ms) = options.to_ms {
            options.to_sample = Some((ms / interval).ceil() as usize);
        }
    }
    if matches!(options.filter_type, VoltageFilterType::Downsampled) && options.downsample <= 1 {
        options.downsample = 2;
        if matches!(options.downsample_mode, DownsampleMode::None) {
            options.downsample_mode = DownsampleMode::Decimate;
        }
    }
    let outputs = write_voltage_chart_package(&report, out_dir, &options)?;
    Ok(VoltageChartPackageReport { path: path.to_path_buf(), outputs })
}

fn load_raw_by_channel(
    path: &Path,
    max_blocks: Option<usize>,
) -> Result<std::collections::BTreeMap<usize, Vec<f64>>> {
    let mut rec = Recording::open(path)?;
    let header = rec.header().clone();
    let mut map: std::collections::BTreeMap<usize, Vec<f64>> = std::collections::BTreeMap::new();
    for (i, block) in rec.blocks().enumerate() {
        if max_blocks.is_some_and(|m| i >= m) {
            break;
        }
        let block = block?;
        for (col, &ch) in block.channel_indices.iter().enumerate() {
            let series = map.entry(ch).or_default();
            for row in &block.samples {
                series.push(header.counts_to_millivolts(row[col]));
            }
        }
    }
    Ok(map)
}

pub fn write_voltage_chart_package(
    report: &AnalysisReport,
    out_dir: impl AsRef<Path>,
    options: &VoltageChartOptions,
) -> 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 stem = &options.name;
    let mut paths = Vec::new();

    let sliced = slice_report(report, options)?;

    for fmt in &options.formats {
        match fmt {
            VoltageChartFormat::Shorts => {
                let bin = dir.join(format!("{stem}.bin"));
                let hdr = dir.join(format!("{stem}.hdr"));
                write_filtered_i16_binary(&sliced, &bin)?;
                write_voltage_hdr(&sliced.header, &sliced, &hdr, false, options.hdr_style)?;
                paths.push(bin);
                paths.push(hdr);
            }
            VoltageChartFormat::Doubles => {
                let bin = dir.join(format!("{stem}_f64.bin"));
                let hdr = dir.join(format!("{stem}_f64.hdr"));
                write_filtered_f64_binary(&sliced, &bin)?;
                write_voltage_hdr(&sliced.header, &sliced, &hdr, true, options.hdr_style)?;
                paths.push(bin);
                paths.push(hdr);
            }
            VoltageChartFormat::Ascii => {
                let csv = dir.join(format!("{stem}.csv"));
                if options.csv_ms932 {
                    write_voltage_chart_csv(&sliced, &csv)?;
                } else {
                    write_voltage_chart_csv_with_charset(&sliced, &csv, false)?;
                }
                paths.push(csv);
            }
            VoltageChartFormat::Mobius => {
                let modat = dir.join(format!("{stem}.modat"));
                // points_per_block=0 → derive from filtered length / block count
                write_filtered_mobius_modat(&sliced, &modat, 0)?;
                paths.push(modat);
            }
        }
    }

    if options.formats.contains(&VoltageChartFormat::Doubles) {
        let f32p = dir.join(format!("{stem}_f32.bin"));
        crate::export_waveform::write_filtered_f32_binary(&sliced, &f32p)?;
        paths.push(f32p);
    }

    let manifest = dir.join("export_manifest.json");
    let body = serde_json::json!({
        "source": report.path.display().to_string(),
        "name": stem,
        "files": paths.iter().map(|p| p.display().to_string()).collect::<Vec<_>>(),
        "downsample": options.downsample,
        "downsample_mode": format!("{:?}", options.downsample_mode),
        "filter_type": options.filter_type as u8,
        "hdr_style": format!("{:?}", options.hdr_style),
    });
    std::fs::write(&manifest, serde_json::to_string_pretty(&body).unwrap())
        .map_err(|source| Med64Error::WriteIo { path: manifest.clone(), source })?;
    paths.push(manifest);
    Ok(paths)
}

fn slice_report(report: &AnalysisReport, options: &VoltageChartOptions) -> Result<AnalysisReport> {
    if report.filtered_by_channel.is_empty() {
        return Err(Med64Error::InvalidWrite {
            message: "voltage chart requires filtered traces (retain_filtered)".into(),
        });
    }
    let n = report.filtered_by_channel.values().map(|v| v.len()).max().unwrap_or(0);
    let from = options.from_sample.unwrap_or(0).min(n);
    let to = options.to_sample.unwrap_or(n).min(n).max(from);
    let factor = options.downsample.max(1);
    let mode = options.downsample_mode;

    let mut filtered = std::collections::BTreeMap::new();
    for (&ch, samples) in &report.filtered_by_channel {
        let window = &samples[from..to.min(samples.len())];
        filtered.insert(ch, downsample_series(window, factor, mode));
    }
    let mut out = report.clone();
    out.filtered_by_channel = filtered;
    Ok(out)
}

fn downsample_series(samples: &[f64], factor: usize, mode: DownsampleMode) -> Vec<f64> {
    if factor <= 1 || matches!(mode, DownsampleMode::None) {
        return samples.to_vec();
    }
    match mode {
        DownsampleMode::None | DownsampleMode::Decimate => {
            samples.iter().step_by(factor).copied().collect()
        }
        DownsampleMode::Average => {
            let mut out = Vec::with_capacity(samples.len() / factor);
            let mut i = 0;
            while i + factor <= samples.len() {
                let sum: f64 = samples[i..i + factor].iter().sum();
                out.push(sum / factor as f64);
                i += factor;
            }
            out
        }
        DownsampleMode::Median => {
            let mut out = Vec::with_capacity(samples.len() / factor);
            let mut i = 0;
            while i + factor <= samples.len() {
                let mut w: Vec<f64> = samples[i..i + factor].to_vec();
                w.sort_by(|a, b| a.partial_cmp(b).unwrap());
                out.push(w[w.len() / 2]);
                i += factor;
            }
            out
        }
    }
}

/// Little-endian f64 millivolts, sample-major Ă— channel (`BinaryexportDouble`).
pub fn write_filtered_f64_binary(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    let path = path.as_ref();
    let mut channels: Vec<usize> = report.filtered_by_channel.keys().copied().collect();
    channels.sort_unstable();
    let n = report.filtered_by_channel.values().map(|v| v.len()).max().unwrap_or(0);
    let mut bytes = Vec::with_capacity(n * channels.len() * 8);
    for i in 0..n {
        for &ch in &channels {
            let mv = report.filtered_by_channel[&ch].get(i).copied().unwrap_or(0.0);
            bytes.extend_from_slice(&mv.to_le_bytes());
        }
    }
    std::fs::write(path, bytes)
        .map_err(|source| Med64Error::WriteIo { path: path.to_path_buf(), source })
}

fn write_voltage_hdr(
    header: &Med64Header,
    report: &AnalysisReport,
    path: impl AsRef<Path>,
    doubles: bool,
    style: VoltageHdrStyle,
) -> Result<()> {
    let path = path.as_ref();
    let mut channels: Vec<usize> = report.filtered_by_channel.keys().copied().collect();
    channels.sort_unstable();
    let mut out = String::new();
    if matches!(style, VoltageHdrStyle::Modat) {
        out.push_str(&format!("Session Start Time, {}\n", header.start_date_time()));
    }
    out.push_str(&format!("Sampling freq (Hz), {}\n", header.sampling_frequency_hz));
    if !doubles {
        out.push_str(&format!("Conversion factor: short to mV, {}\n", header.conversion_factor));
    }
    out.push_str("Active channels,");
    for (i, ch) in channels.iter().enumerate() {
        if i > 0 {
            out.push(' ');
        }
        out.push_str(&(ch + 1).to_string());
    }
    out.push('\n');
    std::fs::write(path, out)
        .map_err(|source| Med64Error::WriteIo { path: path.to_path_buf(), source })
}

/// Voltage Chart CSV: `time_ms,chN…` with `%.2f` time and `%.15f` values.
pub fn write_voltage_chart_csv(report: &AnalysisReport, path: impl AsRef<Path>) -> Result<()> {
    write_voltage_chart_csv_with_charset(report, path, true)
}

pub fn write_voltage_chart_csv_with_charset(
    report: &AnalysisReport,
    path: impl AsRef<Path>,
    ms932: bool,
) -> Result<()> {
    let path = path.as_ref();
    let mut channels: Vec<usize> = report.filtered_by_channel.keys().copied().collect();
    channels.sort_unstable();
    let n = report.filtered_by_channel.values().map(|v| v.len()).max().unwrap_or(0);
    let interval = report.header.interval_ms();
    let mut out = String::from("time_ms");
    for &ch in &channels {
        out.push_str(&format!(",ch{}", ch + 1));
    }
    out.push('\n');
    for i in 0..n {
        out.push_str(&format!("{:.2}", i as f64 * interval));
        for &ch in &channels {
            let mv = report.filtered_by_channel[&ch].get(i).copied().unwrap_or(0.0);
            out.push_str(&format!(",{mv:.15}"));
        }
        out.push('\n');
    }
    crate::toolkit::voltage_chart_prefs::write_text_maybe_ms932(path, &out, ms932)
}

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

    #[test]
    fn average_downsample_halves_length() {
        let s: Vec<f64> = (0..10).map(|i| i as f64).collect();
        let d = downsample_series(&s, 2, DownsampleMode::Average);
        assert_eq!(d.len(), 5);
        assert!((d[0] - 0.5).abs() < 1e-9);
    }
}