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::collections::HashSet;
use std::io::{Read, Write};
use std::path::Path;

use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};

use crate::error::{Med64Error, Result};
use crate::header::Med64Header;

/// Fixed prefix size for each data block header.
pub const DATA_BLOCK_HEADER_BYTES: usize = 35;
pub const DATA_BLOCK_SIZE_FIELD_BYTES: usize = 4;

/// One contiguous chunk of multichannel waveform samples from a `.modat` file.
#[derive(Debug, Clone, PartialEq)]
pub struct Med64DataBlock {
    pub trace_number: u32,
    pub block_number: u32,
    pub trace_offset_ms: f64,
    pub block_offset_ms: f64,
    pub number_of_data_points: u32,
    pub first_block: u8,
    pub last_block: u8,
    pub stimulation_loop_number: u8,
    pub stimulation_step_number: u8,
    pub size_of_data_block: u32,
    /// Physical channel index per column in `samples`.
    pub channel_indices: Vec<usize>,
    /// Raw ADC counts indexed as `[sample_index][channel_column]`.
    pub samples: Vec<Vec<i16>>,
}

impl Med64DataBlock {
    pub(crate) fn read_from<R: Read>(
        path: &Path,
        block_index: usize,
        header: &Med64Header,
        reader: &mut R,
        channel_indices: Option<&[usize]>,
    ) -> Result<Self> {
        let mut block_header = [0u8; DATA_BLOCK_HEADER_BYTES];
        reader.read_exact(&mut block_header).map_err(|source| Med64Error::InvalidBlock {
            path: path.to_path_buf(),
            block_index,
            message: format!("failed to read block header: {source}"),
        })?;

        let mut cursor = std::io::Cursor::new(block_header);
        let trace_number = cursor.read_u32::<LittleEndian>().unwrap();
        let block_number = cursor.read_u32::<LittleEndian>().unwrap();
        let trace_offset_ms = cursor.read_f64::<LittleEndian>().unwrap();
        let block_offset_ms = cursor.read_f64::<LittleEndian>().unwrap();
        let number_of_data_points = cursor.read_u32::<LittleEndian>().unwrap();
        let first_block = cursor.read_u8().unwrap();
        let last_block = cursor.read_u8().unwrap();
        let stimulation_loop_number = cursor.read_u8().unwrap();
        let stimulation_step_number = cursor.read_u8().unwrap();

        let size_of_data_block =
            reader.read_u32::<LittleEndian>().map_err(|source| Med64Error::InvalidBlock {
                path: path.to_path_buf(),
                block_index,
                message: format!("failed to read block payload size: {source}"),
            })?;

        let active_indices = header.active_channel_indices_for(header.num_channel_slots());
        let output_channels = channel_indices
            .map(|requested| {
                requested
                    .iter()
                    .filter(|ch| active_indices.contains(ch))
                    .copied()
                    .collect::<Vec<_>>()
            })
            .unwrap_or_else(|| active_indices.clone());

        let expected_payload = number_of_data_points as u64
            * active_indices.len() as u64
            * std::mem::size_of::<i16>() as u64;

        if u64::from(size_of_data_block) != expected_payload {
            return Err(Med64Error::InvalidBlock {
                path: path.to_path_buf(),
                block_index,
                message: format!(
                    "payload size mismatch: header says {size_of_data_block} bytes, expected {expected_payload} for {} points x {} active channels",
                    number_of_data_points,
                    active_indices.len()
                ),
            });
        }

        let mut samples = vec![vec![0i16; output_channels.len()]; number_of_data_points as usize];
        let want: HashSet<usize> = output_channels.iter().copied().collect();
        let read_all = channel_indices.is_none() || want.len() == active_indices.len();
        let mut skip = [0u8; 2];

        for point in 0..number_of_data_points as usize {
            for &channel_idx in &active_indices {
                if read_all || want.contains(&channel_idx) {
                    let raw = reader.read_i16::<LittleEndian>().map_err(|source| {
                        Med64Error::InvalidBlock {
                            path: path.to_path_buf(),
                            block_index,
                            message: format!(
                                "failed reading sample at point {point}, channel {channel_idx}: {source}"
                            ),
                        }
                    })?;

                    if let Some(col) = output_channels.iter().position(|&ch| ch == channel_idx) {
                        samples[point][col] = raw;
                    }
                } else {
                    reader.read_exact(&mut skip).map_err(|source| Med64Error::InvalidBlock {
                        path: path.to_path_buf(),
                        block_index,
                        message: format!(
                            "failed skipping sample at point {point}, channel {channel_idx}: {source}"
                        ),
                    })?;
                }
            }
        }

        Ok(Self {
            trace_number,
            block_number,
            trace_offset_ms,
            block_offset_ms,
            number_of_data_points,
            first_block,
            last_block,
            stimulation_loop_number,
            stimulation_step_number,
            size_of_data_block,
            channel_indices: output_channels,
            samples,
        })
    }

    /// Write block header + payload compatible with the official MED64 reader.
    pub fn write_to<W: Write>(&self, writer: &mut W, header: &Med64Header) -> Result<()> {
        let active = header.active_channel_indices_for(header.num_channel_slots());
        let payload_len = self.number_of_data_points as u64
            * active.len() as u64
            * std::mem::size_of::<i16>() as u64;

        writer
            .write_u32::<LittleEndian>(self.trace_number)
            .and_then(|_| writer.write_u32::<LittleEndian>(self.block_number))
            .and_then(|_| writer.write_f64::<LittleEndian>(self.trace_offset_ms))
            .and_then(|_| writer.write_f64::<LittleEndian>(self.block_offset_ms))
            .and_then(|_| writer.write_u32::<LittleEndian>(self.number_of_data_points))
            .and_then(|_| writer.write_u8(self.first_block))
            .and_then(|_| writer.write_u8(self.last_block))
            .and_then(|_| writer.write_u8(0))
            .and_then(|_| writer.write_u8(self.stimulation_loop_number))
            .and_then(|_| writer.write_all(&[0u8; DATA_BLOCK_HEADER_BYTES - 32]))
            .and_then(|_| writer.write_u32::<LittleEndian>(payload_len as u32))
            .map_err(|source| Med64Error::WriteIo { path: header.path.clone(), source })?;

        for point in &self.samples {
            for &channel in &active {
                let value = self
                    .channel_indices
                    .iter()
                    .position(|&ch| ch == channel)
                    .map(|col| point[col])
                    .unwrap_or(0);
                writer
                    .write_i16::<LittleEndian>(value)
                    .map_err(|source| Med64Error::WriteIo { path: header.path.clone(), source })?;
            }
        }
        Ok(())
    }

    /// Total on-disk size of this block including headers and payload.
    pub fn on_disk_size(&self) -> u64 {
        (DATA_BLOCK_HEADER_BYTES + DATA_BLOCK_SIZE_FIELD_BYTES) as u64
            + u64::from(self.size_of_data_block)
    }

    /// Convert stored counts for one channel column to millivolts.
    pub fn channel_millivolts(&self, header: &Med64Header, channel_column: usize) -> Vec<f64> {
        self.samples.iter().map(|row| header.counts_to_millivolts(row[channel_column])).collect()
    }
}

#[cfg(test)]
mod tests {
    use crate::reader::Med64Reader;
    use std::path::Path;

    #[test]
    fn reads_first_block_from_sample_data1() {
        let path = &crate::fixture_paths::sample_data1();
        let mut reader = Med64Reader::open(path).unwrap();
        let header = reader.read_header().unwrap();
        let block = reader.next_block(&header, None).unwrap().unwrap();

        assert_eq!(block.trace_number, 0);
        assert_eq!(block.block_number, 0);
        assert_eq!(block.number_of_data_points, 2000);
        assert_eq!(block.samples.len(), 2000);
        assert_eq!(block.samples[0].len(), 64);
        assert_eq!(block.channel_indices.len(), 64);
        assert_eq!(block.samples[0][0], -11);
    }
}