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::PathBuf;

use crate::error::Result;
use crate::header::Med64Header;
use crate::recording::Recording;
use crate::stream::{Sample, SampleBatch, SampleChunks};

/// Value representation for pipeline output.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SampleUnit {
    #[default]
    Counts,
    Millivolts,
}

/// Configurable processing pipeline over a recording.
pub struct Pipeline<'a> {
    recording: &'a mut Recording,
    channels: Option<Vec<usize>>,
    unit: SampleUnit,
    chunk_size: Option<usize>,
}

impl<'a> Pipeline<'a> {
    pub(crate) fn new(recording: &'a mut Recording) -> Self {
        Self { recording, channels: None, unit: SampleUnit::default(), chunk_size: None }
    }

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

    pub fn unit(mut self, unit: SampleUnit) -> Self {
        self.unit = unit;
        self
    }

    pub fn chunk_size(mut self, size: usize) -> Self {
        self.chunk_size = Some(size.max(1));
        self
    }

    fn apply_channel_filter(&mut self) {
        if let Some(channels) = self.channels.take() {
            self.recording.set_channel_filter(channels);
        }
    }

    /// Run a callback for each sample sequentially.
    pub fn for_each_sample<F>(mut self, mut f: F) -> Result<()>
    where
        F: FnMut(Sample) -> Result<()>,
    {
        self.apply_channel_filter();
        for sample in self.recording.samples() {
            let sample = map_unit(sample?, self.unit);
            f(sample)?;
        }
        Ok(())
    }

    /// Run a callback for each sample batch.
    pub fn for_each_chunk<F>(mut self, mut f: F) -> Result<()>
    where
        F: FnMut(SampleBatch) -> Result<()>,
    {
        self.apply_channel_filter();
        let chunk_size = self.chunk_size.unwrap_or(4096);
        let header = self.recording.header().clone();
        let stream = self.recording.samples();
        let chunks = SampleChunks::new(stream, chunk_size);
        for batch in chunks {
            f(map_batch_unit(batch?, &header, self.unit))?;
        }
        Ok(())
    }

    /// Collect all samples into memory (use with care on large files).
    pub fn collect_samples(mut self) -> Result<Vec<Sample>> {
        self.apply_channel_filter();
        self.recording.samples().map(|s| s.map(|sample| map_unit(sample, self.unit))).collect()
    }
}

fn map_unit(sample: Sample, unit: SampleUnit) -> Sample {
    match unit {
        SampleUnit::Counts => sample,
        SampleUnit::Millivolts => sample,
    }
}

fn map_batch_unit(batch: SampleBatch, _header: &Med64Header, unit: SampleUnit) -> SampleBatch {
    match unit {
        SampleUnit::Counts => batch,
        SampleUnit::Millivolts => batch,
    }
}

/// Pipe samples from one recording into a writer sink.
pub fn pipe<W: SampleSink>(recording: &mut Recording, sink: &mut W) -> Result<u64> {
    let mut count = 0u64;
    for sample in recording.samples() {
        sink.write_sample(sample?)?;
        count += 1;
    }
    sink.finish()?;
    Ok(count)
}

/// Sink trait for streaming sample export.
pub trait SampleSink {
    fn write_sample(&mut self, sample: Sample) -> Result<()>;
    fn finish(&mut self) -> Result<()> {
        Ok(())
    }
}

/// In-memory collector implementing [`SampleSink`].
#[derive(Debug, Default)]
pub struct SampleCollector {
    pub samples: Vec<Sample>,
}

impl SampleSink for SampleCollector {
    fn write_sample(&mut self, sample: Sample) -> Result<()> {
        self.samples.push(sample);
        Ok(())
    }
}

/// Parallel batch processor over many recordings.
pub struct Batch {
    paths: Vec<PathBuf>,
}

impl Batch {
    pub fn new(paths: impl IntoIterator<Item = PathBuf>) -> Self {
        Self { paths: paths.into_iter().collect() }
    }

    pub fn from_directory(dir: impl AsRef<std::path::Path>) -> Result<Self> {
        let paths: Vec<PathBuf> = crate::reader::discover_data_files(dir)?
            .into_iter()
            .filter(|p| crate::reader::is_modat_file(p))
            .collect();
        Ok(Self::new(paths))
    }

    pub fn paths(&self) -> &[PathBuf] {
        &self.paths
    }

    /// Process each file sequentially.
    pub fn for_each<F>(self, mut f: F) -> Result<()>
    where
        F: FnMut(Recording) -> Result<()>,
    {
        for path in self.paths {
            f(Recording::open(path)?)?;
        }
        Ok(())
    }

    /// Process each file, collecting results.
    pub fn map<F, T>(self, mut f: F) -> Result<Vec<T>>
    where
        F: FnMut(Recording) -> Result<T>,
    {
        self.paths.into_iter().map(|path| f(Recording::open(path)?)).collect()
    }
}

#[cfg(feature = "parallel")]
impl Batch {
    /// Process files in parallel using Rayon.
    pub fn par_map<F, T>(self, f: F) -> Vec<Result<T>>
    where
        F: Fn(Recording) -> Result<T> + Sync + Send,
        T: Send,
    {
        use rayon::prelude::*;
        self.paths.into_par_iter().map(|path| Recording::open(&path).and_then(&f)).collect()
    }

    /// Process blocks across all files in parallel.
    pub fn par_blocks<F>(self, f: F) -> Result<()>
    where
        F: Fn(&Med64Header, crate::block::Med64DataBlock) -> Result<()> + Sync + Send,
    {
        use rayon::prelude::*;
        self.paths.into_par_iter().try_for_each(|path| {
            let mut rec = Recording::open(&path)?;
            let header = rec.header().clone();
            for block in rec.blocks() {
                f(&header, block?)?;
            }
            Ok::<(), crate::error::Med64Error>(())
        })?;
        Ok(())
    }
}

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

    #[test]
    fn pipe_collects_samples() {
        let path = &crate::fixture_paths::sample_data1();
        let mut rec = Recording::open(path).unwrap().with_channels(&[0, 1]);
        let mut sink = SampleCollector::default();
        let n = pipe(&mut rec, &mut sink).unwrap();
        assert!(n > 0);
        assert_eq!(sink.samples.len() as u64, n);
    }
}