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::Result;
use crate::header::Med64Header;
use crate::pipeline::Pipeline;
use crate::reader::Med64Reader;
use crate::stream::{BlockStream, SampleStream};

/// An opened MED64 `.modat` recording with parsed header metadata.
pub struct Recording {
    path: PathBuf,
    reader: Med64Reader,
    header: Med64Header,
    channel_filter: Option<Vec<usize>>,
}

impl Recording {
    /// Open a recording over an indexed payload region inside a larger file (e.g. PRESTO `.modax`).
    pub fn open_indexed(
        path: impl AsRef<Path>,
        header: Med64Header,
        data_offset: u64,
        data_end: u64,
        block_size: u64,
    ) -> Result<Self> {
        let path = path.as_ref().to_path_buf();
        let reader = Med64Reader::open_indexed(path.clone(), header.clone(), data_offset, data_end, block_size)?;
        Ok(Self {
            path,
            reader,
            header,
            channel_filter: None,
        })
    }

    /// Open a `.modat` recording and parse its header.
    pub fn open(path: impl AsRef<Path>) -> Result<Self> {
        let path = path.as_ref().to_path_buf();
        let mut reader = Med64Reader::open(&path)?;
        let header = reader.read_header()?;
        Ok(Self { path, reader, header, channel_filter: None })
    }

    pub fn path(&self) -> &Path {
        &self.path
    }

    pub fn header(&self) -> &Med64Header {
        &self.header
    }

    pub fn file_size(&self) -> u64 {
        self.reader.file_size()
    }

    /// Restrict subsequent streams to a channel subset (physical channel indices).
    pub fn with_channels(mut self, channels: &[usize]) -> Self {
        self.channel_filter = Some(channels.to_vec());
        self
    }

    pub(crate) fn set_channel_filter(&mut self, channels: Vec<usize>) {
        self.channel_filter = Some(channels);
    }

    /// Lazily stream data blocks without loading the full file into memory.
    pub fn blocks(&mut self) -> BlockStream<'_> {
        let _ = self.reader.seek_block(&self.header, 0);
        BlockStream {
            reader: &mut self.reader,
            header: &self.header,
            channels: self.channel_filter.as_deref(),
            next_index: 0,
            total: self.header.number_of_real_data_blocks as usize,
        }
    }

    /// Flatten all blocks into a per-sample stream `(time, channel, counts, mV)`.
    pub fn samples(&mut self) -> SampleStream<'_> {
        let header = self.header.clone();
        SampleStream::new(self.blocks(), header)
    }

    /// Build a configurable processing pipeline over this recording.
    pub fn pipeline(&mut self) -> Pipeline<'_> {
        Pipeline::new(self)
    }

    /// Seek directly to a block index for random access.
    pub fn seek_block(&mut self, index: usize) -> Result<()> {
        self.reader.seek_block(&self.header, index)
    }

    /// Read one block at the current position.
    pub fn read_block(&mut self) -> Result<Option<crate::block::Med64DataBlock>> {
        self.reader.next_block(&self.header, self.channel_filter.as_deref())
    }
}

/// Open a `.modat` recording (alias for [`Recording::open`]).
pub fn open(path: impl AsRef<Path>) -> Result<Recording> {
    Recording::open(path)
}