Consuming LabBench HDF5 Files from Python

This guide explains how Python users should read and interpret HDF5 files generated by LabBench.

The layout is intentionally simple, deterministic, and compatible with h5py, NumPy, Matlab, and R.

1. Opening a LabBench HDF5 file

import h5py

f = h5py.File("experiment.h5", "r")

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

/root

So typically:

root = f["root"]

2. Scalars (DataNumber, DataBoolean, DataString)

LabBench scalars are stored as datasets.

Example structure:

/root/value

Python:

value = root["value"][()]          # float, bool, or string

3. Vectors (DataVector)

Vectors are stored as 1D numeric datasets.

Structure:

/root/vector        (double[N])

Python:

import numpy as np

vector = root["vector"][()]        # NumPy array

4. Matrices (DataMatrix)

Matrices are stored as 2D datasets.

Structure:

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

Python:

matrix = root["matrix"][()]        # NumPy 2D array

5. Structs (DataStruct)

Structs are stored as HDF5 groups with named children.

Example:

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

Python:

name  = root["name"][()]
a     = root["inner"]["a"][()]
b     = root["inner"]["b"][()]

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
• Ordering is not guaranteed by HDF5
• Ordering must be reconstructed by sorting the keys

Reading an array of scalars

array_group = root["array"]

# Reconstruct in correct order
keys = sorted(array_group.keys())        # ['000', '001', '002']
values = [array_group[k][()] for k in keys]

Now values is a Python list in the correct order.

Arrays of structs

Structure:

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

Python:

channels = []

group = root["channels"]
for k in sorted(group.keys()):
    elem = group[k]
    channels.append({
        "value": elem["value"][()],
        "time":  elem["time"][()]
    })

7. Nested arrays

Nested DataArray objects become nested groups:

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

Python:

outer = root["arrays"]

outer_values = []
for k in sorted(outer.keys()):
    inner_group = outer[k]
    inner = [inner_group[i][()] for i in sorted(inner_group.keys())]
    outer_values.append(inner)

8. NaN and Infinity Handling

LabBench never writes NaN or Infinity directly.

Instead:

Python users should restore semantics if needed:

import numpy as np
import sys

MAX = sys.float_info.max
MIN = -sys.float_info.max

def restore_special(x):
    if x == MAX:
        return np.nan
    if x == MIN:
        return -np.inf
    return x

vector = [restore_special(v) for v in root["values"][()]]

9. Summary of Mapping

10. Design Guarantees

LabBench HDF5 files guarantee:

• One stable root group
• Deterministic names
• No duplicate keys
• No empty names
• Cross-platform compatibility
• Python / Matlab / R safe layout
• Reconstructable array order

11. Typical Full Example

import h5py
import numpy as np

with h5py.File("experiment.h5", "r") as f:
    root = f["root"]

    vector = root["vector"][()]
    matrix = root["matrix"][()]

    array = []
    for k in sorted(root["array"].keys()):
        array.append(root["array"][k][()])

    print(vector)
    print(matrix)
    print(array)

This layout is intentionally minimal and maps cleanly to:

• NumPy arrays
• Python lists and dicts
• Matlab matrices
• R arrays

No special reader library is required beyond h5py.