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::fs::File;
use std::io::{BufReader, Read, Seek, SeekFrom};
use std::path::{Path, PathBuf};

use crate::block::{Med64DataBlock, DATA_BLOCK_HEADER_BYTES, DATA_BLOCK_SIZE_FIELD_BYTES};
use crate::error::{Med64Error, Result};
use crate::header::{Med64Header, FILE_HEADER_BYTES};

/// Buffered read size for sequential block streaming (1 MiB).
const READER_BUFFER_BYTES: usize = 1024 * 1024;

/// Sequential reader for MED64 `.modat` electrophysiology recordings.
pub struct Med64Reader {
    path: PathBuf,
    reader: BufReader<File>,
    file_size: u64,
    data_start: u64,
    block_index: usize,
    cached_block_size: Option<u64>,
    /// Pre-built header for indexed / sliced views (skips on-disk file header read).
    external_header: Option<Med64Header>,
}

impl Med64Reader {
    pub fn open(path: impl AsRef<Path>) -> Result<Self> {
        let path = path.as_ref().to_path_buf();
        let file =
            File::open(&path).map_err(|source| Med64Error::Io { path: path.clone(), source })?;
        let file_size =
            file.metadata().map_err(|source| Med64Error::Io { path: path.clone(), source })?.len();

        Ok(Self {
            path,
            reader: BufReader::with_capacity(READER_BUFFER_BYTES, file),
            file_size,
            data_start: FILE_HEADER_BYTES as u64,
            block_index: 0,
            cached_block_size: None,
            external_header: None,
        })
    }

    /// Open a seek view over an indexed PRESTO `.modax` payload region (no temp copy).
    pub fn open_indexed(
        path: PathBuf,
        header: Med64Header,
        data_offset: u64,
        data_end: u64,
        block_size: u64,
    ) -> Result<Self> {
        let file = File::open(&path).map_err(|source| Med64Error::Io { path: path.clone(), source })?;
        Ok(Self {
            path,
            reader: BufReader::with_capacity(READER_BUFFER_BYTES, file),
            file_size: data_end,
            data_start: data_offset,
            block_index: 0,
            cached_block_size: Some(block_size),
            external_header: Some(header),
        })
    }

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

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

    /// Parse the 123-byte file header and compute block counts from file size.
    pub fn read_header(&mut self) -> Result<Med64Header> {
        if let Some(header) = self.external_header.clone() {
            self.block_index = 0;
            return Ok(header);
        }
        self.reader
            .seek(SeekFrom::Start(0))
            .map_err(|source| Med64Error::Io { path: self.path.clone(), source })?;

        let mut header = Med64Header::read_from(&self.path, &mut self.reader)?;
        self.data_start = self
            .reader
            .stream_position()
            .map_err(|source| Med64Error::Io { path: self.path.clone(), source })?;
        let block_size = self.peek_block_size(&header)?;
        header.finalize_block_counts(self.file_size, block_size);
        self.block_index = 0;
        Ok(header)
    }

    /// Read the next data block, or `None` at EOF.
    pub fn next_block(
        &mut self,
        header: &Med64Header,
        channel_indices: Option<&[usize]>,
    ) -> Result<Option<Med64DataBlock>> {
        if self.at_eof()? {
            return Ok(None);
        }

        let block = Med64DataBlock::read_from(
            &self.path,
            self.block_index,
            header,
            &mut self.reader,
            channel_indices,
        )?;
        self.cached_block_size = Some(block.on_disk_size());
        self.block_index += 1;
        Ok(Some(block))
    }

    /// Jump directly to a block index (0-based).
    pub fn seek_block(&mut self, header: &Med64Header, index: usize) -> Result<()> {
        let block_size = self.ensure_block_size(header)?;
        let offset = self.data_start + block_size * index as u64;
        if offset >= self.file_size {
            return Err(Med64Error::InvalidBlock {
                path: self.path.clone(),
                block_index: index,
                message: format!("block index {index} starts past EOF"),
            });
        }

        self.reader
            .seek(SeekFrom::Start(offset))
            .map_err(|source| Med64Error::Io { path: self.path.clone(), source })?;
        self.block_index = index;
        Ok(())
    }

    /// Collect all data blocks in the file.
    pub fn read_all_blocks(
        &mut self,
        header: &Med64Header,
        channel_indices: Option<&[usize]>,
    ) -> Result<Vec<Med64DataBlock>> {
        self.seek_block(header, 0)?;
        let mut blocks = Vec::with_capacity(header.number_of_real_data_blocks as usize);
        while let Some(block) = self.next_block(header, channel_indices)? {
            blocks.push(block);
        }
        Ok(blocks)
    }

    fn at_eof(&mut self) -> Result<bool> {
        let pos = self
            .reader
            .stream_position()
            .map_err(|source| Med64Error::Io { path: self.path.clone(), source })?;
        Ok(pos >= self.file_size)
    }

    fn ensure_block_size(&mut self, header: &Med64Header) -> Result<u64> {
        if let Some(size) = self.cached_block_size {
            return Ok(size);
        }
        self.peek_block_size(header)
    }

    fn peek_block_size(&mut self, header: &Med64Header) -> Result<u64> {
        if let Some(size) = self.cached_block_size {
            if size > 0 {
                return Ok(size);
            }
        }
        let saved = self
            .reader
            .stream_position()
            .map_err(|source| Med64Error::Io { path: self.path.clone(), source })?;

        self.reader
            .seek(SeekFrom::Start(self.data_start))
            .map_err(|source| Med64Error::Io { path: self.path.clone(), source })?;

        let mut block_header = [0u8; DATA_BLOCK_HEADER_BYTES];
        self.reader.read_exact(&mut block_header).map_err(|source| Med64Error::InvalidBlock {
            path: self.path.clone(),
            block_index: 0,
            message: format!("failed to peek block header: {source}"),
        })?;

        let mut size_buf = [0u8; DATA_BLOCK_SIZE_FIELD_BYTES];
        self.reader.read_exact(&mut size_buf).map_err(|source| Med64Error::InvalidBlock {
            path: self.path.clone(),
            block_index: 0,
            message: format!("failed to peek block size: {source}"),
        })?;

        let payload_size = u32::from_le_bytes(size_buf);
        let block_size = (DATA_BLOCK_HEADER_BYTES + DATA_BLOCK_SIZE_FIELD_BYTES) as u64
            + u64::from(payload_size);

        let expected_payload = header.num_data_points_per_block() as u64
            * header.num_active_channels() as u64
            * std::mem::size_of::<i16>() as u64;

        if u64::from(payload_size) != expected_payload {
            return Err(Med64Error::InvalidBlock {
                path: self.path.clone(),
                block_index: 0,
                message: format!(
                    "first block payload is {payload_size} bytes, expected {expected_payload}"
                ),
            });
        }

        self.cached_block_size = Some(block_size);
        self.reader
            .seek(SeekFrom::Start(saved))
            .map_err(|source| Med64Error::Io { path: self.path.clone(), source })?;
        Ok(block_size)
    }
}

/// Discover `.modat` and `.moflo` files under a directory tree.
pub fn discover_data_files(root: impl AsRef<Path>) -> Result<Vec<PathBuf>> {
    let root = root.as_ref();
    let mut files = Vec::new();
    discover_recursive(root, &mut files)?;
    files.sort();
    Ok(files)
}

fn discover_recursive(dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
    for entry in std::fs::read_dir(dir)
        .map_err(|source| Med64Error::Io { path: dir.to_path_buf(), source })?
    {
        let entry = entry.map_err(|source| Med64Error::Io { path: dir.to_path_buf(), source })?;
        let path = entry.path();
        if path.is_dir() {
            discover_recursive(&path, out)?;
        } else if is_med64_data_file(&path) {
            out.push(path);
        }
    }
    Ok(())
}

pub fn is_modat_file(path: &Path) -> bool {
    path.extension()
        .and_then(|ext| ext.to_str())
        .map(|ext| ext.eq_ignore_ascii_case("modat"))
        .unwrap_or(false)
}

pub fn is_moflo_file(path: &Path) -> bool {
    path.extension()
        .and_then(|ext| ext.to_str())
        .map(|ext| ext.eq_ignore_ascii_case("moflo"))
        .unwrap_or(false)
}

pub fn is_waveform_recording(path: &Path) -> bool {
    path.extension()
        .and_then(|ext| ext.to_str())
        .map(|ext| matches!(ext.to_ascii_lowercase().as_str(), "modat" | "dat" | "dax" | "modax"))
        .unwrap_or(false)
}

pub fn is_med64_data_file(path: &Path) -> bool {
    is_waveform_recording(path) || is_moflo_file(path)
}

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

    #[test]
    fn discovers_files_in_data_dir() {
        let files = discover_data_files(crate::fixture_paths::data_dir()).unwrap();
        assert!(files.iter().any(|p| p.ends_with("sample data1.modat")));
        assert!(files.iter().any(|p| p.ends_with("sample data6.moflo")));
    }
}