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
//! SIS-compatible HDF5 writers (`hdf5-no-c`).
//!
//! Layout mirrors the spike-detector HDF5 export shape:
//! - `ch{N}-trace{T}-timestamp (ms)` float arrays
//! - optional `ch{N}-trace{T}-filtered` / `-rawdata`
//! - `/InfoChannel/*` and `/InfoTimeStamp/*` metadata arrays
//! - `Time (ms)` sample clock when filtered traces are present

use std::collections::BTreeMap;
use std::path::Path;

use crate::analysis::AnalysisReport;
use crate::error::{Med64Error, Result};
use crate::recording::Recording;

#[derive(Debug, Clone)]
pub struct SpikeHdf5Options {
    pub include_timestamps: bool,
    pub include_filtered: bool,
    /// Write `chN-traceT-rawdata` from the source recording (mV float32).
    pub include_raw: bool,
    /// Write a compact `/med64` sidecar (spikes + bursts) for Rust round-trips.
    pub include_med64_sidecar: bool,
    /// When true, emit one dataset set per (channel,trace). When false, force `trace1`
    /// for filtered/raw (merged analysis window).
    pub merge_traces: bool,
    /// Default 1-based trace index when `merge_traces` is false.
    pub default_trace: u32,
    /// h5export uses 0-based ChannelID / SourceChannelIDs.
    pub zero_based_channel_ids: bool,
    /// Round timestamps to this many decimal places (BigDecimal `%.3f`).
    pub timestamp_decimals: u32,
}

impl Default for SpikeHdf5Options {
    fn default() -> Self {
        Self {
            include_timestamps: true,
            include_filtered: true,
            include_raw: false,
            include_med64_sidecar: true,
            merge_traces: true,
            default_trace: 1,
            zero_based_channel_ids: true,
            timestamp_decimals: 3,
        }
    }
}

/// Write spike detector / FBO–style SIS HDF5 layout using `hdf5-no-c`.
pub fn write_spike_hdf5(
    report: &AnalysisReport,
    path: impl AsRef<Path>,
    options: &SpikeHdf5Options,
) -> Result<()> {
    use hdf5::File;

    let path = path.as_ref();
    let h5 = File::create(path).map_err(|err| Med64Error::InvalidWrite {
        message: format!("HDF5 create failed: {err}"),
    })?;

    let interval_ms = report.header.interval_ms();
    let mut by_trace_channel: BTreeMap<(u32, usize), Vec<f32>> = BTreeMap::new();
    for spike in &report.spikes.spikes {
        let trace = if options.merge_traces {
            spike.trace
        } else {
            options.default_trace.saturating_sub(1)
        };
        let t = round_ms(spike.within_trace_time_ms, options.timestamp_decimals);
        by_trace_channel.entry((trace, spike.channel)).or_default().push(t);
    }

    let mut channel_ids: Vec<i32> = Vec::new();
    let mut stamp_entity: Vec<i32> = Vec::new();
    let mut stamp_group: Vec<i32> = Vec::new();
    let mut stamp_source: Vec<i32> = Vec::new();
    let mut entity = 0i32; // TimeStampEntityID starts aligned with 0-based ch ids

    if options.include_timestamps {
        for ((trace, channel), times) in &by_trace_channel {
            if times.is_empty() {
                continue;
            }
            let ch1 = (*channel as i32) + 1;
            let tr1 = (*trace as i32) + 1;
            let name = format!("ch{ch1}-trace{tr1}-timestamp (ms)");
            write_f32_dataset(&h5, &name, times)?;
            let id = if options.zero_based_channel_ids { *channel as i32 } else { ch1 };
            if !channel_ids.contains(&id) {
                channel_ids.push(id);
            }
            stamp_entity.push(id);
            stamp_group.push(0);
            stamp_source.push(id);
            entity = entity.max(id + 1);
        }
        let _ = entity;
    }

    let force_trace1 = !options.merge_traces;
    if options.include_filtered && !report.filtered_by_channel.is_empty() {
        let mut max_len = 0usize;
        for (channel, samples) in &report.filtered_by_channel {
            if samples.is_empty() {
                continue;
            }
            max_len = max_len.max(samples.len());
            let ch1 = (*channel as i32) + 1;
            let tr = if force_trace1 { options.default_trace.max(1) } else { 1 };
            let name = format!("ch{ch1}-trace{tr}-filtered");
            let data: Vec<f32> = samples.iter().map(|&v| v as f32).collect();
            write_f32_dataset(&h5, &name, &data)?;
            let id = if options.zero_based_channel_ids { *channel as i32 } else { ch1 };
            if !channel_ids.contains(&id) {
                channel_ids.push(id);
            }
        }
        if max_len > 0 && interval_ms > 0.0 {
            let time: Vec<f32> = (0..max_len)
                .map(|i| round_ms(i as f64 * interval_ms, options.timestamp_decimals))
                .collect();
            write_f32_dataset(&h5, "Time (ms)", &time)?;
        }
    }

    if options.include_raw {
        write_raw_datasets(&h5, report, options, &mut channel_ids)?;
    }

    if channel_ids.is_empty() {
        for ch in report.header.active_channel_indices() {
            let id = if options.zero_based_channel_ids { ch as i32 } else { ch as i32 + 1 };
            channel_ids.push(id);
        }
    }
    channel_ids.sort_unstable();
    channel_ids.dedup();

    let n = channel_ids.len();
    let raw_type: Vec<String> = (0..n).map(|_| "float32".into()).collect();
    let units: Vec<String> = (0..n).map(|_| "mV".into()).collect();
    let exponents = vec![0i32; n];
    let stamp_units: Vec<String> = (0..stamp_entity.len()).map(|_| "ms".into()).collect();
    let stamp_labels: Vec<String> = stamp_source
        .iter()
        .map(|c| {
            let label_n = if options.zero_based_channel_ids { c + 1 } else { *c };
            format!("Ch{label_n}")
        })
        .collect();
    let stamp_exponents = vec![0i32; stamp_entity.len()];

    write_i32_dataset(&h5, "/InfoChannel/ChannelID", &channel_ids)?;
    write_string_dataset(&h5, "/InfoChannel/RawDataType", &raw_type)?;
    write_string_dataset(&h5, "/InfoChannel/Unit", &units)?;
    write_i32_dataset(&h5, "/InfoChannel/Exponent", &exponents)?;

    if !stamp_entity.is_empty() {
        write_i32_dataset(&h5, "/InfoTimeStamp/TimeStampEntityID", &stamp_entity)?;
        write_i32_dataset(&h5, "/InfoTimeStamp/GroupID", &stamp_group)?;
        write_string_dataset(&h5, "/InfoTimeStamp/Label", &stamp_labels)?;
        write_string_dataset(&h5, "/InfoTimeStamp/Unit", &stamp_units)?;
        write_i32_dataset(&h5, "/InfoTimeStamp/Exponent", &stamp_exponents)?;
        write_i32_dataset(&h5, "/InfoTimeStamp/SourceChannelIDs", &stamp_source)?;
        write_string_dataset(&h5, "/InfoTimeStamp/SourceChannelLabels", &stamp_labels)?;
    }

    if options.include_med64_sidecar {
        write_med64_sidecar(&h5, report)?;
    }

    Ok(())
}

fn write_raw_datasets(
    h5: &hdf5::File,
    report: &AnalysisReport,
    options: &SpikeHdf5Options,
    channel_ids: &mut Vec<i32>,
) -> Result<()> {
    let mut rec = Recording::open(&report.path)?;
    let header = rec.header().clone();
    let n_slots = header.num_channel_slots();
    let mut by_ch: Vec<Vec<f64>> = vec![Vec::new(); n_slots];
    for (bi, block) in rec.blocks().enumerate() {
        // Bound to analyzed span when max_blocks was used — best-effort full raw.
        let _ = bi;
        let block = block?;
        for (col, &ch) in block.channel_indices.iter().enumerate() {
            if ch >= n_slots {
                continue;
            }
            for row in &block.samples {
                by_ch[ch].push(header.counts_to_millivolts(row[col]));
            }
        }
    }
    let tr = options.default_trace.max(1);
    for (ch, samples) in by_ch.iter().enumerate() {
        if samples.is_empty() {
            continue;
        }
        let ch1 = ch as i32 + 1;
        let name = format!("ch{ch1}-trace{tr}-rawdata");
        let data: Vec<f32> = samples.iter().map(|&v| v as f32).collect();
        write_f32_dataset(h5, &name, &data)?;
        let id = if options.zero_based_channel_ids { ch as i32 } else { ch1 };
        if !channel_ids.contains(&id) {
            channel_ids.push(id);
        }
    }
    Ok(())
}

fn round_ms(v: f64, decimals: u32) -> f32 {
    let f = 10f64.powi(decimals as i32);
    ((v * f).round() / f) as f32
}

fn write_f32_dataset(file: &hdf5::File, name: &str, data: &[f32]) -> Result<()> {
    ensure_parent_groups(file, name)?;
    file.new_dataset_builder().with_data(data).create(name).map_err(|err| {
        Med64Error::InvalidWrite { message: format!("HDF5 dataset `{name}` failed: {err}") }
    })?;
    Ok(())
}

fn write_i32_dataset(file: &hdf5::File, name: &str, data: &[i32]) -> Result<()> {
    ensure_parent_groups(file, name)?;
    file.new_dataset_builder().with_data(data).create(name).map_err(|err| {
        Med64Error::InvalidWrite { message: format!("HDF5 dataset `{name}` failed: {err}") }
    })?;
    Ok(())
}

fn write_string_dataset(file: &hdf5::File, name: &str, data: &[String]) -> Result<()> {
    ensure_parent_groups(file, name)?;
    let width = data.iter().map(|s| s.len()).max().unwrap_or(1).max(1);
    let mut bytes = Vec::with_capacity(data.len() * width);
    for s in data {
        let mut row = vec![0u8; width];
        let take = s.len().min(width);
        row[..take].copy_from_slice(&s.as_bytes()[..take]);
        bytes.extend_from_slice(&row);
    }
    if data.is_empty() {
        let empty: [u8; 0] = [];
        file.new_dataset_builder().with_data(&empty).create(name).map_err(|err| {
            Med64Error::InvalidWrite { message: format!("HDF5 dataset `{name}` failed: {err}") }
        })?;
        return Ok(());
    }
    let flat = bytes;
    let ds = file.new_dataset_builder().with_data(&flat).create(name).map_err(|err| {
        Med64Error::InvalidWrite { message: format!("HDF5 dataset `{name}` failed: {err}") }
    })?;
    ds.new_attr_builder().with_data(&[width as u32]).create("fixed_ascii_width").map_err(
        |err| Med64Error::InvalidWrite { message: format!("HDF5 attr on `{name}` failed: {err}") },
    )?;
    ds.new_attr_builder().with_data(&[data.len() as u32]).create("count").map_err(|err| {
        Med64Error::InvalidWrite { message: format!("HDF5 attr on `{name}` failed: {err}") }
    })?;
    Ok(())
}

fn ensure_parent_groups(file: &hdf5::File, path: &str) -> Result<()> {
    let path = path.trim_start_matches('/');
    let parts: Vec<&str> = path.split('/').collect();
    if parts.len() < 2 {
        return Ok(());
    }
    let mut acc = String::new();
    for p in &parts[..parts.len() - 1] {
        if acc.is_empty() {
            acc.push_str(p);
        } else {
            acc.push('/');
            acc.push_str(p);
        }
        if file.group(&acc).is_err() {
            file.create_group(&acc).map_err(|err| Med64Error::InvalidWrite {
                message: format!("HDF5 group `{acc}` failed: {err}"),
            })?;
        }
    }
    Ok(())
}

fn write_med64_sidecar(file: &hdf5::File, report: &AnalysisReport) -> Result<()> {
    let root = file.create_group("med64").map_err(|err| Med64Error::InvalidWrite {
        message: format!("HDF5 med64 group failed: {err}"),
    })?;
    let meta = root.create_group("metadata").map_err(|err| Med64Error::InvalidWrite {
        message: format!("HDF5 med64/metadata failed: {err}"),
    })?;
    write_attr_f64(&meta, "sampling_frequency_hz", report.header.sampling_frequency_hz)?;
    write_attr_f64(&meta, "trace_duration_ms", report.header.real_trace_duration_ms)?;

    let spikes = root.create_group("spikes").map_err(|err| Med64Error::InvalidWrite {
        message: format!("HDF5 med64/spikes failed: {err}"),
    })?;
    let channel: Vec<i32> = report.spikes.spikes.iter().map(|s| s.channel as i32).collect();
    let within: Vec<f64> = report.spikes.spikes.iter().map(|s| s.within_trace_time_ms).collect();
    spikes.new_dataset_builder().with_data(&channel).create("channel").map_err(|err| {
        Med64Error::InvalidWrite { message: format!("HDF5 med64 spikes channel failed: {err}") }
    })?;
    spikes.new_dataset_builder().with_data(&within).create("within_trace_time_ms").map_err(
        |err| Med64Error::InvalidWrite { message: format!("HDF5 med64 spikes time failed: {err}") },
    )?;

    let bursts = root.create_group("bursts").map_err(|err| Med64Error::InvalidWrite {
        message: format!("HDF5 med64/bursts failed: {err}"),
    })?;
    let b_ch: Vec<i32> = report.single_bursts.iter().map(|b| b.channel as i32).collect();
    let b_start: Vec<f64> = report.single_bursts.iter().map(|b| b.start_ms).collect();
    let b_end: Vec<f64> = report.single_bursts.iter().map(|b| b.end_ms).collect();
    bursts.new_dataset_builder().with_data(&b_ch).create("channel").map_err(|err| {
        Med64Error::InvalidWrite { message: format!("HDF5 burst channel failed: {err}") }
    })?;
    bursts.new_dataset_builder().with_data(&b_start).create("start_ms").map_err(|err| {
        Med64Error::InvalidWrite { message: format!("HDF5 burst start failed: {err}") }
    })?;
    bursts.new_dataset_builder().with_data(&b_end).create("end_ms").map_err(|err| {
        Med64Error::InvalidWrite { message: format!("HDF5 burst end failed: {err}") }
    })?;
    Ok(())
}

fn write_attr_f64(group: &hdf5::Group, name: &str, value: f64) -> Result<()> {
    group.new_attr_builder().with_data(&[value]).create(name).map_err(|err| {
        Med64Error::InvalidWrite { message: format!("HDF5 attr `{name}` failed: {err}") }
    })?;
    Ok(())
}