Consuming LabBench HDF5 Files from MATLAB

This guide explains how MATLAB users should read and interpret HDF5 files generated by LabBench using the PureHDF-based exporter.

The layout is intentionally simple, deterministic, and compatible with MATLAB’s built-in h5read, h5info, and array handling.

1. Opening a LabBench HDF5 file

In MATLAB, HDF5 files are accessed using h5info and h5read.

info = h5info('experiment.h5');

All data lives under a single top-level group named after the root object:

/root

So typically all reads are under:

'/root/...'

2. Scalars (DataNumber, DataBoolean, DataString)

LabBench scalars are stored as datasets.

Example structure:

/root/value

MATLAB:

value = h5read('experiment.h5', '/root/value');

Result type:

• double for DataNumber
• logical for DataBoolean
• char or string for DataString

3. Vectors (DataVector)

Vectors are stored as 1D numeric datasets.

Structure:

/root/vector        (double[N])

MATLAB:

vector = h5read('experiment.h5', '/root/vector');

This returns a MATLAB column vector or row vector depending on storage layout.

4. Matrices (DataMatrix)

Matrices are stored as 2D datasets.

Structure:

/root/matrix        (double[rows, cols])

MATLAB:

matrix = h5read('experiment.h5', '/root/matrix');

The matrix is returned directly as a standard MATLAB 2D array.

5. Structs (DataStruct)

Structs are stored as HDF5 groups with named children.

Example layout:

/root
    /name            (string)
    /inner
        /a           (double)
        /b           (bool)

MATLAB:

name  = h5read('experiment.h5', '/root/name');
a     = h5read('experiment.h5', '/root/inner/a');
b     = h5read('experiment.h5', '/root/inner/b');

This naturally maps to MATLAB variables or can be assembled into a struct:

inner.a = a;
inner.b = b;

rootStruct.name  = name;
rootStruct.inner = inner;

6. Arrays (DataArray) — IMPORTANT

LabBench arrays are stored as groups whose children are indexed datasets or groups.

Layout

Example DataArray with 3 elements:

/root/array
    /000
    /001
    /002

Key properties:

• Elements are named with zero-padded indices
• HDF5 group order is not guaranteed
• Order must be reconstructed by sorting names numerically

Reading an array of scalars

info = h5info('experiment.h5', '/root/array');

% Get and sort element names
names = {info.Datasets.Name};
names = sort(names);

values = zeros(numel(names), 1);

for i = 1:numel(names)
    path = ['/root/array/' names{i}];
    values(i) = h5read('experiment.h5', path);
end

Now values is a correctly ordered MATLAB vector.

Arrays of structs

Structure:

/root/channels
    /000
        /value
        /time
    /001
        /value
        /time

MATLAB:

info = h5info('experiment.h5', '/root/channels');

names = {info.Groups.Name};
names = sort(names);

channels = struct([]);

for i = 1:numel(names)
    base = names{i};
    channels(i).value = h5read('experiment.h5', [base '/value']);
    channels(i).time  = h5read('experiment.h5', [base '/time']);
end

7. Nested arrays

Nested DataArray objects become nested groups:

/root/arrays
    /000
        /000
        /001
    /001
        /000
        /001

MATLAB:

outerInfo = h5info('experiment.h5', '/root/arrays');
outerNames = sort({outerInfo.Groups.Name});

outerValues = {};

for i = 1:numel(outerNames)
    innerInfo = h5info('experiment.h5', outerNames{i});
    innerNames = sort({innerInfo.Datasets.Name});

    inner = zeros(numel(innerNames), 1);
    for j = 1:numel(innerNames)
        path = [outerNames{i} '/' innerNames{j}];
        inner(j) = h5read('experiment.h5', path);
    end

    outerValues{i} = inner;
end

8. NaN and Infinity Handling

LabBench never writes NaN or Infinity directly.

Instead:

MATLAB restoration:

MAX = realmax;
MIN = -realmax;

function y = restore_special(x)
    y = x;
    y(x == MAX) = NaN;
    y(x == MIN) = -Inf;
end

vector = restore_special(h5read('experiment.h5', '/root/values'));

9. Summary of Mapping

10. Design Guarantees

LabBench HDF5 files guarantee:

• One stable root group
• Deterministic zero-padded array indices
• No duplicate keys
• No empty names
• Cross-platform compatibility
• MATLAB-safe layout
• Reconstructable array order

11. Typical Full Example

info = h5info('experiment.h5');
root = '/root';

vector = h5read('experiment.h5', [root '/vector']);
matrix = h5read('experiment.h5', [root '/matrix']);

arrayInfo = h5info('experiment.h5', [root '/array']);
names = sort({arrayInfo.Datasets.Name});

array = zeros(numel(names), 1);
for i = 1:numel(names)
    array(i) = h5read('experiment.h5', [root '/array/' names{i}]);
end

disp(vector);
disp(matrix);
disp(array);

This layout is intentionally minimal and maps cleanly to:

• MATLAB numeric arrays
• MATLAB structs
• Cell arrays and vectors
• Time series and signal processing workflows

No additional toolboxes are required beyond MATLAB’s built-in HDF5 support.