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::block::Med64DataBlock;
use crate::error::Result;
use crate::header::Med64Header;
use crate::recording::Recording;

/// Controls how much data diagnostics scans.
#[derive(Debug, Clone)]
pub struct DiagnosticOptions {
    /// Limit block scan count (`None` = entire file).
    pub max_blocks: Option<usize>,
    /// Physical channel indices to include (`None` = all active).
    pub channels: Option<Vec<usize>>,
}

impl Default for DiagnosticOptions {
    fn default() -> Self {
        Self { max_blocks: Some(10), channels: None }
    }
}

/// Full diagnostic report for a recording.
#[derive(Debug, Clone)]
pub struct Diagnostics {
    pub path: PathBuf,
    pub header: HeaderSummary,
    pub blocks: Vec<BlockSummary>,
    pub channels: Vec<ChannelStats>,
    pub warnings: Vec<String>,
}

#[derive(Debug, Clone)]
pub struct HeaderSummary {
    pub sampling_frequency_hz: f64,
    pub interval_ms: f64,
    pub ms_per_block: u32,
    pub num_blocks: u32,
    pub num_active_channels: usize,
    pub real_trace_duration_ms: f64,
    pub conversion_factor: f64,
    pub start_timestamp: String,
}

#[derive(Debug, Clone)]
pub struct BlockSummary {
    pub index: usize,
    pub trace_number: u32,
    pub block_number: u32,
    pub offset_ms: f64,
    pub num_points: u32,
    pub first_block: u8,
    pub last_block: u8,
}

#[derive(Debug, Clone)]
pub struct ChannelStats {
    pub channel: usize,
    pub sample_count: u64,
    pub min_counts: i16,
    pub max_counts: i16,
    pub min_mv: f64,
    pub max_mv: f64,
    pub mean_mv: f64,
    pub rms_mv: f64,
    pub peak_to_peak_mv: f64,
    pub flat_ratio: f64,
    pub notes: Vec<String>,
}

/// Collect diagnostics by streaming blocks (does not load full file).
pub fn analyze(recording: &mut Recording, options: &DiagnosticOptions) -> Result<Diagnostics> {
    let header = recording.header().clone();
    let selected = resolve_channels(&header, options.channels.as_deref());

    let mut accumulators: Vec<StatsAccumulator> =
        selected.iter().map(|&ch| StatsAccumulator::new(ch)).collect();

    let mut blocks = Vec::new();
    let mut warnings = Vec::new();
    let mut prev_offset: Option<f64> = None;
    let max_blocks = options.max_blocks.unwrap_or(usize::MAX);

    for (index, block_result) in recording.blocks().enumerate() {
        if index >= max_blocks {
            break;
        }
        let block = block_result?;
        check_block_gaps(&block, prev_offset, &mut warnings);
        prev_offset = Some(block.block_offset_ms + block.trace_offset_ms);

        blocks.push(summarize_block(index, &block));
        update_channel_stats(&header, &block, &selected, &mut accumulators);
    }

    if blocks.is_empty() {
        warnings.push("no data blocks found".into());
    }

    let channels: Vec<ChannelStats> =
        accumulators.into_iter().map(|acc| acc.finish(&header)).collect();

    for ch in &channels {
        if ch.peak_to_peak_mv < 0.001 {
            warnings.push(format!(
                "channel {} appears flat (peak-to-peak {:.6} mV)",
                ch.channel, ch.peak_to_peak_mv
            ));
        }
        if ch.flat_ratio > 0.95 {
            warnings.push(format!(
                "channel {} is {:.0}% constant samples",
                ch.channel,
                ch.flat_ratio * 100.0
            ));
        }
    }

    Ok(Diagnostics {
        path: recording.path().to_path_buf(),
        header: summarize_header(&header),
        blocks,
        channels,
        warnings,
    })
}

pub fn analyze_path(path: impl AsRef<Path>, options: &DiagnosticOptions) -> Result<Diagnostics> {
    let mut rec = Recording::open(path)?;
    if let Some(channels) = &options.channels {
        rec = rec.with_channels(channels);
    }
    analyze(&mut rec, options)
}

fn resolve_channels(header: &Med64Header, requested: Option<&[usize]>) -> Vec<usize> {
    match requested {
        Some(ch) => ch.to_vec(),
        None => header.active_channel_indices(),
    }
}

fn summarize_header(header: &Med64Header) -> HeaderSummary {
    HeaderSummary {
        sampling_frequency_hz: header.sampling_frequency_hz,
        interval_ms: header.interval_ms(),
        ms_per_block: header.ms_per_block(),
        num_blocks: header.number_of_real_data_blocks,
        num_active_channels: header.num_active_channels(),
        real_trace_duration_ms: header.real_trace_duration_ms,
        conversion_factor: header.conversion_factor,
        start_timestamp: format!(
            "{:04}-{:02}-{:02} {:02}:{:02}:{:02}.{:03}",
            header.start_year,
            header.start_month,
            header.start_day,
            header.start_hour(),
            header.start_minute(),
            header.start_second(),
            header.start_millisecond()
        ),
    }
}

fn summarize_block(index: usize, block: &Med64DataBlock) -> BlockSummary {
    BlockSummary {
        index,
        trace_number: block.trace_number,
        block_number: block.block_number,
        offset_ms: block.block_offset_ms + block.trace_offset_ms,
        num_points: block.number_of_data_points,
        first_block: block.first_block,
        last_block: block.last_block,
    }
}

fn check_block_gaps(block: &Med64DataBlock, prev: Option<f64>, warnings: &mut Vec<String>) {
    if let Some(prev_ms) = prev {
        let gap = (block.block_offset_ms + block.trace_offset_ms - prev_ms).abs();
        if gap > 0.001 && block.block_number > 0 {
            // gaps are normal between blocks; only warn on large unexpected jumps
            if gap > 10_000.0 {
                warnings.push(format!(
                    "large timeline gap ({gap:.1} ms) before block {}",
                    block.block_number
                ));
            }
        }
    }
}

fn update_channel_stats(
    header: &Med64Header,
    block: &Med64DataBlock,
    selected: &[usize],
    accumulators: &mut [StatsAccumulator],
) {
    let interval = header.interval_ms();
    let base_ms = block.block_offset_ms + block.trace_offset_ms;

    for (point_idx, row) in block.samples.iter().enumerate() {
        let _time_ms = base_ms + point_idx as f64 * interval;
        for (col, &channel) in block.channel_indices.iter().enumerate() {
            if let Some(acc_idx) = selected.iter().position(|&c| c == channel) {
                let counts = row[col];
                let mv = header.counts_to_millivolts(counts);
                accumulators[acc_idx].push(counts, mv);
            }
        }
    }
}

struct StatsAccumulator {
    channel: usize,
    count: u64,
    min_counts: i16,
    max_counts: i16,
    min_mv: f64,
    max_mv: f64,
    mean: f64,
    m2: f64,
    sum_sq: f64,
    sum_sq_mv: f64,
    last_mv: Option<f64>,
    flat_runs: u64,
}

impl StatsAccumulator {
    fn new(channel: usize) -> Self {
        Self {
            channel,
            count: 0,
            min_counts: i16::MAX,
            max_counts: i16::MIN,
            min_mv: f64::INFINITY,
            max_mv: f64::NEG_INFINITY,
            mean: 0.0,
            m2: 0.0,
            sum_sq: 0.0,
            sum_sq_mv: 0.0,
            last_mv: None,
            flat_runs: 0,
        }
    }

    fn push(&mut self, counts: i16, mv: f64) {
        self.count += 1;
        self.min_counts = self.min_counts.min(counts);
        self.max_counts = self.max_counts.max(counts);
        self.min_mv = self.min_mv.min(mv);
        self.max_mv = self.max_mv.max(mv);
        self.sum_sq += f64::from(counts).powi(2);
        self.sum_sq_mv += mv * mv;

        let delta = mv - self.mean;
        self.mean += delta / self.count as f64;
        let delta2 = mv - self.mean;
        self.m2 += delta * delta2;

        if let Some(last) = self.last_mv {
            if (mv - last).abs() < 1e-12 {
                self.flat_runs += 1;
            }
        }
        self.last_mv = Some(mv);
    }

    fn finish(self, _header: &Med64Header) -> ChannelStats {
        let _variance = if self.count > 1 { self.m2 / (self.count - 1) as f64 } else { 0.0 };
        let rms_mv = (self.sum_sq_mv / self.count.max(1) as f64).sqrt();

        let mut notes = Vec::new();
        if self.count == 0 {
            notes.push("no samples".into());
        }

        ChannelStats {
            channel: self.channel,
            sample_count: self.count,
            min_counts: if self.count > 0 { self.min_counts } else { 0 },
            max_counts: if self.count > 0 { self.max_counts } else { 0 },
            min_mv: if self.count > 0 { self.min_mv } else { 0.0 },
            max_mv: if self.count > 0 { self.max_mv } else { 0.0 },
            mean_mv: if self.count > 0 { self.mean } else { 0.0 },
            rms_mv,
            peak_to_peak_mv: if self.count > 0 { self.max_mv - self.min_mv } else { 0.0 },
            flat_ratio: if self.count > 0 {
                self.flat_runs as f64 / self.count as f64
            } else {
                0.0
            },
            notes,
        }
    }
}

impl Diagnostics {
    pub fn print_report(&self) {
        println!("Diagnostics: {}", self.path.display());
        println!(
            "  sample rate: {:.0} Hz ({:.4} ms/sample)",
            self.header.sampling_frequency_hz, self.header.interval_ms
        );
        println!(
            "  blocks: {} scanned / {} total, {:.1} ms captured",
            self.blocks.len(),
            self.header.num_blocks,
            self.header.real_trace_duration_ms
        );
        println!("  channels: {}", self.header.num_active_channels);
        println!();
        println!(
            "  {:>3} {:>8} {:>10} {:>10} {:>10} {:>8}",
            "ch", "samples", "mean mV", "rms mV", "p-p mV", "flat%"
        );
        for ch in &self.channels {
            println!(
                "  {:>3} {:>8} {:>10.4} {:>10.4} {:>10.4} {:>7.1}",
                ch.channel,
                ch.sample_count,
                ch.mean_mv,
                ch.rms_mv,
                ch.peak_to_peak_mv,
                ch.flat_ratio * 100.0
            );
        }
        if !self.warnings.is_empty() {
            println!();
            println!("Warnings:");
            for w in &self.warnings {
                println!("  - {w}");
            }
        }
    }
}

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

    #[test]
    fn analyzes_sample_data1() {
        let report = analyze_path(
            crate::fixture_paths::sample_data1(),
            &DiagnosticOptions { max_blocks: Some(2), channels: Some(vec![0, 1]) },
        )
        .unwrap();
        assert_eq!(report.channels.len(), 2);
        assert!(!report.blocks.is_empty());
        assert!(report.channels[0].sample_count > 0);
    }
}