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
//! Block-streaming analysis state (memory-bounded per trace segment).

use std::collections::HashMap;

use crate::analysis::filter::{BandpassFilter, FilterAlgorithm, LowPassKind};
use crate::analysis::spike::{
    attach_waveforms, calc_thresholds, detect_spikes, detect_spikes_f32, SpikeDetectOptions,
    SpikeTrain, ThresholdOptions,
};
use crate::header::Med64Header;

/// Per-channel filter + detection context for incremental block processing.
#[derive(Debug)]
pub struct ChannelStreamState {
    pub channel: usize,
    filter: BandpassFilter,
    pub samples: Vec<f64>,
    trace: u32,
    trace_offset_ms: f64,
    thresholds_computed: bool,
    plus_mv: f64,
    minus_mv: f64,
}

impl ChannelStreamState {
    pub fn new(
        channel: usize,
        sample_rate_hz: f64,
        highpass_hz: f64,
        lowpass_hz: f64,
        lowpass_kind: LowPassKind,
        filter_algorithm: FilterAlgorithm,
    ) -> Self {
        let sample_period = 1.0 / sample_rate_hz;
        Self {
            channel,
            filter: BandpassFilter::with_algorithm(
                sample_period,
                highpass_hz,
                lowpass_hz,
                lowpass_kind,
                filter_algorithm,
            ),
            samples: Vec::new(),
            trace: 0,
            trace_offset_ms: 0.0,
            thresholds_computed: false,
            plus_mv: 0.5,
            minus_mv: -0.5,
        }
    }

    pub fn filter_reset(&mut self) {
        self.filter.reset();
    }

    #[allow(dead_code)]
    pub fn reset_trace(&mut self, trace: u32, trace_offset_ms: f64) {
        self.trace = trace;
        self.trace_offset_ms = trace_offset_ms;
        self.filter.reset();
        self.samples.clear();
        self.thresholds_computed = false;
    }

    pub fn push_block(&mut self, mv_samples: &[f64]) {
        let mut buf = mv_samples.to_vec();
        self.filter.filter_block(&mut buf);
        if self.filter.algorithm() == FilterAlgorithm::SecondPole {
            for v in &mut buf {
                *v = (*v as f32) as f64;
            }
        }
        self.samples.extend(buf);
    }

    pub fn ensure_thresholds(
        &mut self,
        threshold_opts: &ThresholdOptions,
        plus_fixed: Option<f64>,
        minus_fixed: Option<f64>,
        window_samples: usize,
    ) {
        if self.thresholds_computed {
            return;
        }
        let window = if window_samples == 0 {
            self.samples.as_slice()
        } else {
            &self.samples[..window_samples.min(self.samples.len())]
        };
        let fixed = match (plus_fixed, minus_fixed) {
            (Some(p), Some(m)) if p != 0.0 || m != 0.0 => Some((p, m)),
            _ => None,
        };
        let t = calc_thresholds(window, threshold_opts, fixed);
        self.plus_mv = t.plus_mv;
        self.minus_mv = t.minus_mv;
        self.thresholds_computed = true;
    }

    pub fn detect(
        &mut self,
        header: &Med64Header,
        interval_ms: f64,
        refractory_samples: usize,
        pre_ms: f64,
        post_ms: f64,
        use_f32_detect: bool,
        detect_plus: bool,
        detect_minus: bool,
    ) -> SpikeTrain {
        if self.samples.is_empty() {
            return SpikeTrain::default();
        }
        let opts = SpikeDetectOptions {
            plus_threshold_mv: self.plus_mv,
            minus_threshold_mv: self.minus_mv,
            refractory_samples: refractory_samples.max(1),
            trace: self.trace,
            channel: self.channel,
            block_offset_ms: self.trace_offset_ms,
            session_offset_ms: 0.0,
            detect_plus,
            detect_minus,
        };
        let mut train = if use_f32_detect {
            detect_spikes_f32(header, &self.samples, &opts)
        } else {
            detect_spikes(header, &self.samples, &opts)
        };
        attach_waveforms(
            &mut train,
            &self.samples,
            self.channel,
            interval_ms,
            pre_ms,
            post_ms,
            self.trace_offset_ms,
        );
        train
    }

    pub fn clear(&mut self) {
        self.samples.clear();
        self.filter.reset();
        self.thresholds_computed = false;
    }
}

/// Trace-segment accumulator keyed by channel index.
#[derive(Debug, Default)]
pub struct TraceSegment {
    pub trace: u32,
    pub trace_offset_ms: f64,
    pub channels: HashMap<usize, ChannelStreamState>,
}

impl TraceSegment {
    pub fn flush(
        &mut self,
        header: &Med64Header,
        interval_ms: f64,
        threshold_opts: &ThresholdOptions,
        plus_thresholds: Option<&[f64]>,
        minus_thresholds: Option<&[f64]>,
        pre_ms: &[f64],
        post_ms: &[f64],
        window_samples: usize,
        refractory_samples: usize,
        use_f32_detect: bool,
        detect_plus: bool,
        detect_minus: bool,
    ) -> SpikeTrain {
        #[cfg(feature = "parallel")]
        {
            use rayon::prelude::*;
            let channels: Vec<(usize, ChannelStreamState)> = self.channels.drain().collect();
            let parts: Vec<SpikeTrain> = channels
                .into_par_iter()
                .map(|(ch, mut state)| {
                    let plus = plus_thresholds.and_then(|v| v.get(ch).copied());
                    let minus = minus_thresholds.and_then(|v| v.get(ch).copied());
                    state.ensure_thresholds(threshold_opts, plus, minus, window_samples);
                    let pre = pre_ms.get(ch).copied().unwrap_or(1.0);
                    let post = post_ms.get(ch).copied().unwrap_or(2.5);
                    let part = state.detect(
                        header,
                        interval_ms,
                        refractory_samples,
                        pre,
                        post,
                        use_f32_detect,
                        detect_plus,
                        detect_minus,
                    );
                    state.clear();
                    part
                })
                .collect();
            let mut out = SpikeTrain::default();
            for mut part in parts {
                out.spikes.append(&mut part.spikes);
            }
            out
        }
        #[cfg(not(feature = "parallel"))]
        {
            let mut out = SpikeTrain::default();
            for (ch, state) in self.channels.iter_mut() {
                let plus = plus_thresholds.and_then(|v| v.get(*ch).copied());
                let minus = minus_thresholds.and_then(|v| v.get(*ch).copied());
                state.ensure_thresholds(threshold_opts, plus, minus, window_samples);
                let pre = pre_ms.get(*ch).copied().unwrap_or(1.0);
                let post = post_ms.get(*ch).copied().unwrap_or(2.5);
                let mut part = state.detect(
                    header,
                    interval_ms,
                    refractory_samples,
                    pre,
                    post,
                    use_f32_detect,
                    detect_plus,
                    detect_minus,
                );
                out.spikes.append(&mut part.spikes);
                state.clear();
            }
            out
        }
    }
}

/// Apply per-channel spike cap (`maxSpikes` from workflows).
pub fn apply_max_spikes_per_channel(train: SpikeTrain, max: Option<usize>) -> SpikeTrain {
    let Some(max) = max else {
        return train;
    };
    let mut by_channel: HashMap<usize, Vec<_>> = HashMap::new();
    for spike in train.spikes {
        by_channel.entry(spike.channel).or_default().push(spike);
    }
    let mut kept = SpikeTrain::default();
    for mut spikes in by_channel.into_values() {
        spikes.sort_by(|a, b| a.within_trace_time_ms.partial_cmp(&b.within_trace_time_ms).unwrap());
        spikes.truncate(max);
        kept.spikes.extend(spikes);
    }
    kept.spikes.sort_by(|a, b| {
        a.within_trace_time_ms
            .partial_cmp(&b.within_trace_time_ms)
            .unwrap()
            .then(a.channel.cmp(&b.channel))
    });
    kept
}

/// Build per-channel vector filled with a scalar default.
pub fn per_channel_values(scalar: f64, channels: &[usize], n: usize) -> Vec<f64> {
    let mut out = vec![scalar; n];
    for &ch in channels {
        if ch < n {
            out[ch] = scalar;
        }
    }
    out
}

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

    #[test]
    fn max_spikes_truncates_per_channel() {
        let mut train = SpikeTrain::default();
        for i in 0..5 {
            train.spikes.push(crate::analysis::spike::Spike {
                channel: 0,
                within_trace_time_ms: i as f64,
                ..Default::default()
            });
        }
        let kept = apply_max_spikes_per_channel(train, Some(2));
        assert_eq!(kept.len(), 2);
    }
}