matreader

matreader is both a Rust crate and a CLI tool for inspecting MATLAB v5 .mat files that contain EEG data (or any combination of numeric arrays, structs, cells, and strings). It was written to work with large EEG datasets that nest trials inside cell arrays and store channel metadata in structs.

Features

• Walks the full MATLAB v5 hierarchy (numeric matrices, structs, cells, and char arrays).
• Summary mode streams through data to report dimensions, dtype, and a short preview without loading full matrices.
• Full mode (optional) captures raw numeric values, with a configurable per-array limit to avoid blowing out memory.
• Built-in to_ndarray() helper converts captured numeric arrays into ndarray::ArrayD<f64> for downstream processing.
• Command-line interface for quick inspection; library API for embedding in your own Rust projects.

Install / Build

cargo build

CLI Usage

# Summaries only (default)
cargo run -- S1_Session_1.mat

# Capture up to 200 elements per array, and render as ndarray
cargo run -- --mode full --max-values 200 --ndarray S1_Session_1.mat

Output is a tree of variables. Each numeric entry prints dimensions, dtype, a handful of leading values, and either the raw numbers or an ndarray dump (if requested).

Library Usage Example

use matreader::{MatFile, MatValue, ParseMode};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let file = std::fs::File::open("S1_Session_1.mat")?;
    let mat = MatFile::parse_reader(file, ParseMode::Full { max_values: 10_000 })?;

    for value in mat.values {
        if let MatValue::Numeric(summary) = value {
            if let Some(array) = summary.to_ndarray() {
                println!("{} has ndarray shape {:?}", summary.name, array.shape());
            }
        }
    }

    Ok(())
}

Direct ndarray extraction

If you only need the numeric matrices, you can let the crate collect them for you:

use matreader::MatFile;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let file = std::fs::File::open("S1_Session_1.mat")?;
    let arrays = MatFile::parse_ndarrays(file, 10_000)?;

    println!("loaded {} arrays", arrays.len());
    for array in arrays {
        println!("shape: {:?}", array.shape());
    }

    Ok(())
}

Notes

• Only MATLAB v5 little-endian files are supported. v7.3 (HDF5-based) files are not.
• When arrays exceed the max_values threshold in full mode, the reader falls back to summaries and marks them as truncated.
• The helper script scripts/write_sample.sh runs the tool on S1_Session_1.mat and captures the first 200 output lines in test.txt.