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::path::{Path, PathBuf};

use crate::error::{Med64Error, Result};
use crate::format::FileFormat;
use crate::moflo::MofloProtocol;
use crate::recording::Recording;
use crate::writer::Writer;

/// Options controlling file conversion.
#[derive(Debug, Clone)]
pub struct ConvertOptions {
    pub channels: Option<Vec<usize>>,
    pub json_include_samples: bool,
    /// Keep every Nth sample (1 = no downsample). Matches wire `downsampling`.
    pub downsample: usize,
}

impl Default for ConvertOptions {
    fn default() -> Self {
        Self { channels: None, json_include_samples: false, downsample: 1 }
    }
}

/// Summary returned after a conversion completes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ConvertReport {
    pub source: PathBuf,
    pub target: PathBuf,
    pub source_format: FileFormat,
    pub target_format: FileFormat,
    pub blocks_written: u32,
    pub samples_written: u64,
}

impl ConvertOptions {
    pub fn channels(mut self, channels: &[usize]) -> Self {
        self.channels = Some(channels.to_vec());
        self
    }

    pub fn json_include_samples(mut self, include: bool) -> Self {
        self.json_include_samples = include;
        self
    }
}

/// Convert between supported MED64 formats.
pub fn convert(
    source: impl AsRef<Path>,
    target: impl AsRef<Path>,
    options: &ConvertOptions,
) -> Result<ConvertReport> {
    let source = source.as_ref();
    let target = target.as_ref();
    let source_format = FileFormat::from_path(source).ok_or_else(|| Med64Error::InvalidHeader {
        path: source.to_path_buf(),
        message: "unknown source format".into(),
    })?;
    let target_format = FileFormat::from_path(target).ok_or_else(|| Med64Error::InvalidHeader {
        path: target.to_path_buf(),
        message: "unknown target format".into(),
    })?;

    if !target_format.is_writable() {
        return Err(Med64Error::NotWritable { format: target_format });
    }

    match (source_format, target_format) {
        (
            FileFormat::Modat | FileFormat::Dat | FileFormat::Dax | FileFormat::Modax,
            FileFormat::Modat,
        ) => copy_modat(source, target, options),
        (
            FileFormat::Modat | FileFormat::Dat | FileFormat::Dax | FileFormat::Modax,
            FileFormat::Csv,
        ) => export_modat(source, target, options, false),
        (
            FileFormat::Modat | FileFormat::Dat | FileFormat::Dax | FileFormat::Modax,
            FileFormat::Json,
        ) => export_modat(source, target, options, true),
        (FileFormat::Moflo, FileFormat::Csv | FileFormat::Json | FileFormat::Modat) => {
            convert_moflo_replays(source, target, target_format, options)
        }
        _ => Err(Med64Error::UnsupportedConversion { from: source_format, to: target_format }),
    }
}

fn copy_modat(source: &Path, target: &Path, options: &ConvertOptions) -> Result<ConvertReport> {
    let mut rec = open_filtered(source, options)?;
    let mut header = rec.header().clone();
    if let Some(channels) = &options.channels {
        header.active_channels = [0u8; crate::header::NUM_CHANNELS];
        for &ch in channels {
            if ch < crate::header::NUM_CHANNELS {
                header.active_channels[ch] = 1;
            }
        }
    }
    let factor = options.downsample.max(1);
    if factor > 1 {
        header.sampling_frequency_hz /= factor as f64;
    }
    let mut writer = Writer::modat(target, header.clone())?;
    let mut blocks = 0u32;
    let mut samples = 0u64;
    for block in rec.blocks() {
        let mut block = block?;
        if factor > 1 {
            downsample_block(&mut block, factor);
        }
        samples += block.samples.len() as u64 * block.channel_indices.len() as u64;
        writer.write_block(&header, &block)?;
        blocks += 1;
    }
    writer.finish()?;
    Ok(ConvertReport {
        source: source.to_path_buf(),
        target: target.to_path_buf(),
        source_format: FileFormat::Modat,
        target_format: FileFormat::Modat,
        blocks_written: blocks,
        samples_written: samples,
    })
}

fn export_modat(
    source: &Path,
    target: &Path,
    options: &ConvertOptions,
    json: bool,
) -> Result<ConvertReport> {
    let mut rec = open_filtered(source, options)?;
    let header = rec.header().clone();
    let mut writer = if json {
        Writer::json(target, &header, options.json_include_samples)?
    } else {
        Writer::csv(target)?
    };
    let mut blocks = 0u32;
    let mut samples = 0u64;
    let factor = options.downsample.max(1);
    for block in rec.blocks() {
        let mut block = block?;
        if factor > 1 {
            downsample_block(&mut block, factor);
        }
        samples += block.samples.len() as u64 * block.channel_indices.len() as u64;
        writer.write_block(&header, &block)?;
        blocks += 1;
    }
    writer.finish()?;
    Ok(ConvertReport {
        source: source.to_path_buf(),
        target: target.to_path_buf(),
        source_format: FileFormat::Modat,
        target_format: if json { FileFormat::Json } else { FileFormat::Csv },
        blocks_written: blocks,
        samples_written: samples,
    })
}

fn convert_moflo_replays(
    source: &Path,
    target: &Path,
    _target_format: FileFormat,
    options: &ConvertOptions,
) -> Result<ConvertReport> {
    let protocol = MofloProtocol::from_file(source)?;
    let replays = protocol.resolve_replay_paths(source);
    if replays.len() != 1 {
        return Err(Med64Error::InvalidMoflo {
            path: source.to_path_buf(),
            message: format!("expected exactly one replay target, found {}", replays.len()),
        });
    }
    convert(&replays[0], target, options).map(|mut report| {
        report.source = source.to_path_buf();
        report
    })
}

fn downsample_block(block: &mut crate::block::Med64DataBlock, factor: usize) {
    if factor <= 1 || block.samples.is_empty() {
        return;
    }
    let n_ch = block.channel_indices.len();
    let mut out = Vec::new();
    for chunk in block.samples.chunks(factor) {
        let mut acc = vec![0i32; n_ch];
        for row in chunk {
            for (i, &v) in row.iter().enumerate() {
                acc[i] += i32::from(v);
            }
        }
        let n = chunk.len() as i32;
        out.push(acc.into_iter().map(|s| (s / n) as i16).collect());
    }
    block.samples = out;
    block.number_of_data_points = block.samples.len() as u32;
    block.size_of_data_block = (block.samples.len() * n_ch * 2) as u32;
}

fn open_filtered(source: &Path, options: &ConvertOptions) -> Result<Recording> {
    let rec = crate::formats::open_recording_any(source)?;
    Ok(match &options.channels {
        Some(ch) => rec.with_channels(ch),
        None => rec,
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::recording::Recording;
    use std::path::PathBuf;

    fn temp_path(name: &str) -> PathBuf {
        std::env::temp_dir().join(format!("med64-{name}-{}.modat", std::process::id()))
    }

    fn temp_csv(name: &str) -> PathBuf {
        std::env::temp_dir().join(format!("med64-{name}-{}.csv", std::process::id()))
    }

    #[test]
    fn modat_roundtrip_first_block() {
        let src = &crate::fixture_paths::sample_data1();
        let dst = temp_path("roundtrip");
        let _ = std::fs::remove_file(&dst);

        convert(src, &dst, &ConvertOptions::default().channels(&[0, 1, 2])).unwrap();

        let mut original = Recording::open(src).unwrap().with_channels(&[0, 1, 2]);
        let mut copied = Recording::open(&dst).unwrap().with_channels(&[0, 1, 2]);
        let b0 = original.blocks().next().unwrap().unwrap();
        let b1 = copied.blocks().next().unwrap().unwrap();
        assert_eq!(b0.samples, b1.samples);
        assert_eq!(copied.header().num_active_channels(), 3);
        let _ = std::fs::remove_file(dst);
    }

    #[test]
    fn converts_to_csv() {
        let src = &crate::fixture_paths::sample_data1();
        let dst = temp_csv("out");
        let _ = std::fs::remove_file(&dst);
        let report = convert(src, &dst, &ConvertOptions::default().channels(&[0])).unwrap();
        assert!(report.samples_written > 0);
        assert!(dst.exists());
        let content = std::fs::read_to_string(&dst).unwrap();
        assert!(content.starts_with("time_ms,channel,counts,millivolts\n"));
        let _ = std::fs::remove_file(dst);
    }
}