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
//! Fast Burst Onset (FBO99) batch: activation map + SIS HDF5 + `.modat` re-export.

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

use serde::{Deserialize, Serialize};

use crate::analysis::{run_analysis, AnalysisOptions, AnalysisReport};
use crate::block::Med64DataBlock;
use crate::error::{Med64Error, Result};
use crate::toolkit::activation::{activation_from_spikes, ActivationOptions, ActivationReport};
use crate::writer::ModatWriter;

#[derive(Debug, Clone)]
pub struct FboOptions {
    pub analysis: AnalysisOptions,
    pub activation: ActivationOptions,
    pub export_hdf5: bool,
    /// Write filtered waveforms as a Mobius-compatible `.modat`.
    pub export_mobius_modat: bool,
    /// Samples per block when writing `.modat` (0 = keep source block size).
    pub points_per_block: usize,
    /// Destination for `.modat` (default: temp dir).
    pub mobius_out: Option<PathBuf>,
    /// Destination for HDF5 (default: temp dir).
    pub hdf5_out: Option<PathBuf>,
}

impl Default for FboOptions {
    fn default() -> Self {
        let mut analysis = AnalysisOptions::reference();
        analysis.retain_filtered = true;
        analysis.max_blocks = Some(20);
        Self {
            analysis,
            activation: ActivationOptions::default(),
            export_hdf5: true,
            export_mobius_modat: true,
            points_per_block: 0,
            mobius_out: None,
            hdf5_out: None,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FboReport {
    pub path: PathBuf,
    pub activation: ActivationReport,
    pub hdf5_path: Option<PathBuf>,
    pub mobius_modat_path: Option<PathBuf>,
    pub spike_count: usize,
}

/// Run FBO-style activation analysis and optionally write SIS HDF5 + filtered `.modat`.
pub fn run_fbo(path: impl AsRef<Path>, options: &FboOptions) -> Result<FboReport> {
    let path = path.as_ref();
    let mut analysis = options.analysis.clone();
    if options.export_hdf5 || options.export_mobius_modat {
        analysis.retain_filtered = true;
    }
    let report = run_analysis(path, &analysis)?;
    let activation = activation_from_spikes(path, &report.spikes, &options.activation);

    let hdf5_path = if options.export_hdf5 {
        let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("fbo");
        let out = options
            .hdf5_out
            .clone()
            .unwrap_or_else(|| std::env::temp_dir().join(format!("{stem}.fbo.h5")));
        #[cfg(feature = "hdf5")]
        {
            use crate::export::{write_spike_hdf5, SpikeHdf5Options};
            write_spike_hdf5(&report, &out, &SpikeHdf5Options::default())?;
            Some(out)
        }
        #[cfg(not(feature = "hdf5"))]
        {
            let _ = out;
            None
        }
    } else {
        None
    };

    let mobius_modat_path = if options.export_mobius_modat {
        let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("fbo");
        let out = options
            .mobius_out
            .clone()
            .unwrap_or_else(|| std::env::temp_dir().join(format!("{stem}_filtered.modat")));
        write_filtered_mobius_modat(&report, &out, options.points_per_block)?;
        Some(out)
    } else {
        None
    };

    Ok(FboReport {
        path: path.to_path_buf(),
        activation,
        hdf5_path,
        mobius_modat_path,
        spike_count: report.spikes.len(),
    })
}

/// Re-export filtered millivolt traces as a `.modat` can open (FBO `mobiusexport`).
pub fn write_filtered_mobius_modat(
    report: &AnalysisReport,
    path: impl AsRef<Path>,
    points_per_block: usize,
) -> Result<()> {
    let path = path.as_ref();
    if report.filtered_by_channel.is_empty() {
        return Err(Med64Error::InvalidWrite {
            message: "no filtered traces; set AnalysisOptions.retain_filtered".into(),
        });
    }
    let mut channels: Vec<usize> = report.filtered_by_channel.keys().copied().collect();
    channels.sort_unstable();
    let n_samples = report.filtered_by_channel.values().map(|v| v.len()).max().unwrap_or(0);
    if n_samples == 0 {
        return Err(Med64Error::InvalidWrite { message: "filtered traces are empty".into() });
    }

    let mut header = report.header.clone();
    header.path = path.to_path_buf();
    header.extended_active_channels = None;
    header.active_channels = [0u8; crate::header::NUM_CHANNELS];
    for &ch in &channels {
        if ch < crate::header::NUM_CHANNELS {
            header.active_channels[ch] = 1;
        }
    }

    let ppb = if points_per_block > 0 {
        points_per_block
    } else {
        header.num_data_points_per_block().max(1) as usize
    };
    let ms_per_block = ppb as f64 * 1000.0 / header.sampling_frequency_hz.max(1.0);
    let n_blocks = n_samples.div_ceil(ppb);
    header.number_of_traces = 1;
    header.blocks_per_trace = n_blocks.max(1) as u32;
    header.trace_duration_ms = ms_per_block * header.blocks_per_trace as f64;
    header.number_of_real_data_blocks = n_blocks as u32;
    header.real_trace_duration_ms = n_samples as f64 * header.interval_ms();

    let mut writer = ModatWriter::create(path, header.clone())?;
    let interval_ms = header.interval_ms();
    for block_idx in 0..n_blocks {
        let start = block_idx * ppb;
        let end = (start + ppb).min(n_samples);
        let points = end - start;
        let mut samples = Vec::with_capacity(ppb);
        for i in 0..points {
            let mut row = Vec::with_capacity(channels.len());
            for &ch in &channels {
                let series = &report.filtered_by_channel[&ch];
                let mv = series.get(start + i).copied().unwrap_or(0.0);
                row.push(header.millivolts_to_counts(mv));
            }
            samples.push(row);
        }
        while samples.len() < ppb {
            samples.push(vec![0i16; channels.len()]);
        }
        let payload = (ppb * channels.len() * 2) as u32;
        let block = Med64DataBlock {
            trace_number: 0,
            block_number: block_idx as u32,
            trace_offset_ms: 0.0,
            block_offset_ms: start as f64 * interval_ms,
            number_of_data_points: ppb as u32,
            first_block: u8::from(block_idx == 0),
            last_block: u8::from(block_idx + 1 == n_blocks),
            stimulation_loop_number: 0,
            stimulation_step_number: 0,
            size_of_data_block: payload,
            channel_indices: channels.clone(),
            samples,
        };
        writer.write_block(&block)?;
    }
    writer.finish()?;
    Ok(())
}

/// Batch FBO Filteringbatch options (template `fbo` overridden per input path).
#[derive(Debug, Clone)]
pub struct FboBatchOptions {
    pub fbo: FboOptions,
    pub export_hdf5: bool,
    pub export_mobius_modat: bool,
    pub highpass_hz: Option<f64>,
    pub lowpass_hz: Option<f64>,
    pub downsample: usize,
    pub max_blocks: Option<usize>,
}

impl Default for FboBatchOptions {
    fn default() -> Self {
        Self {
            fbo: FboOptions::default(),
            export_hdf5: true,
            export_mobius_modat: true,
            highpass_hz: None,
            lowpass_hz: None,
            downsample: 1,
            max_blocks: None,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FboBatchFileResult {
    pub path: PathBuf,
    pub report: Option<FboReport>,
    pub error: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FboBatchReport {
    pub out_dir: PathBuf,
    pub files: Vec<FboBatchFileResult>,
}

/// Run FBO filtering/export over many `.modat` / `.modax` / `.dat` inputs.
/// Continues on per-file errors and writes `batch_manifest.json` under `out_dir`.
pub fn run_fbo_filtering_batch(
    inputs: &[PathBuf],
    out_dir: impl AsRef<Path>,
    options: &FboBatchOptions,
) -> Result<FboBatchReport> {
    let out_dir = out_dir.as_ref().to_path_buf();
    std::fs::create_dir_all(&out_dir)
        .map_err(|source| Med64Error::Io { path: out_dir.clone(), source })?;

    let mut files = Vec::with_capacity(inputs.len());
    for input in inputs {
        let stem = input.file_stem().and_then(|s| s.to_str()).unwrap_or("fbo");
        let file_dir = out_dir.join(stem);
        let _ = std::fs::create_dir_all(&file_dir);

        let mut fbo = options.fbo.clone();
        fbo.export_hdf5 = options.export_hdf5;
        fbo.export_mobius_modat = options.export_mobius_modat;
        if let Some(hp) = options.highpass_hz {
            fbo.analysis.highpass_hz = Some(hp);
        }
        if let Some(lp) = options.lowpass_hz {
            fbo.analysis.lowpass_hz = Some(lp);
        }
        if options.downsample > 1 {
            fbo.analysis.reduce = options.downsample;
        }
        if let Some(n) = options.max_blocks {
            fbo.analysis.max_blocks = Some(n);
        }
        if fbo.export_hdf5 || fbo.export_mobius_modat {
            fbo.analysis.retain_filtered = true;
        }
        fbo.hdf5_out = Some(file_dir.join(format!("{stem}.fbo.h5")));
        fbo.mobius_out = Some(file_dir.join(format!("{stem}_filtered.modat")));

        let entry = match run_fbo(input, &fbo) {
            Ok(report) => {
                FboBatchFileResult { path: input.clone(), report: Some(report), error: None }
            }
            Err(e) => {
                FboBatchFileResult { path: input.clone(), report: None, error: Some(e.to_string()) }
            }
        };
        files.push(entry);
    }

    let report = FboBatchReport { out_dir: out_dir.clone(), files };
    let manifest = out_dir.join("batch_manifest.json");
    let json = serde_json::to_string_pretty(&report).map_err(|source| {
        Med64Error::InvalidWrite { message: format!("batch_manifest json: {source}") }
    })?;
    std::fs::write(&manifest, json)
        .map_err(|source| Med64Error::WriteIo { path: manifest, source })?;
    Ok(report)
}

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

    #[test]
    fn fbo_batch_sample_data1_and_data6() {
        let dir = std::env::temp_dir().join(format!("med64-fbo-batch-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let inputs =
            vec![crate::fixture_paths::sample_data1(), crate::fixture_paths::sample_data6_cap()];
        let opts = FboBatchOptions {
            export_hdf5: false,
            export_mobius_modat: true,
            max_blocks: Some(2),
            downsample: 1,
            ..FboBatchOptions::default()
        };
        let report = run_fbo_filtering_batch(&inputs, &dir, &opts).unwrap();
        assert_eq!(report.files.len(), 2);
        assert!(report.files.iter().all(|f| f.error.is_none()), "{:?}", report.files);
        assert!(dir.join("batch_manifest.json").exists());
        for f in &report.files {
            let r = f.report.as_ref().unwrap();
            assert!(r.mobius_modat_path.as_ref().unwrap().exists());
        }
        let _ = std::fs::remove_dir_all(&dir);
    }
}