dh5io 0.4.0

Python tools for DAQ-HDF5 (dh5) file format used at Brain Research Institute of University of Bremen

Python Tools for the DAQ-HDF5 format

A Python package for handling DAQ-HDF5(*.dh5) files. The DH5 format is a hierarchical data format based on HDF5 designed for storing and sharing neurophysiology data, used in the Brain Research Institute of the University of Bremen since 2005.

• dhspec contains the specification of the DAQ-HDF5 file format as Python code.
• dh5io contains code for reading, writing and validating HDF5 files containing data according to the DAQ-HDF5 specfication.
• dh5neo (WIP) contains code for reading DAQ-HDF5 data into Neo objects (e.g. for use with Elephant, SpikeInterface and ephyviewer

Getting started

Installation

Install the package using uv (recommended):

uv pip install dh5io

Or with pip:

pip install dh5io

Reading and writing from and into DH5 files

from dh5io.dh5file import DH5File

with DH5File(example_filename, "r") as dh5:
    # inspect file content
    print(dh5)

    cont = dh5.get_cont_group_by_id(1)  # Get CONT group with id 1
    print(cont)

    trialmap = dh5.get_trialmap()
    print(trialmap)

  DAQ-HDF5 File (version 2) <example_filename> containing:
      ├───CONT Groups (7):
      │   ├─── CONT1
      │   ├─── CONT60
      │   ├─── CONT61
      │   ├─── CONT62
      │   ├─── CONT63
      │   ├─── CONT64
      │   └─── CONT1001
      ├───SPIKE Groups (1):
      │   └─── SPIKE0
      ├─── 10460 Events
      └─── 385 Trials in TRIALMAP

  /CONT1 in <example_filename>
      ├─── id: 1
      ├─── name:
      ├─── comment:
      ├─── sample_period: 1000000 ns (1000.0 Hz)
      ├─── n_channels: 1
      ├─── n_samples: 1443184
      ├─── duration: 3021.76 s
      ├─── n_regions: 385
      ├─── signal_type: None
      ├─── calibration: [1.0172526e-07]
      ├─── data: (1443184, 1)
      └─── index: (385,)

This example shows how to open a DH5 file, inspect its content, and retrieve a specific CONT group. The DH5File class provides methods for accessing the various groups and datasets within the file. The Cont, Spike (coming in next versions) and Trialmap classes provide convenient wrappers for working with these raw HDF5 groups and datasets. The corresponding h5py classes can be accessed directly for lower-level operations using the _file, _group and _dataset attributes (e.g. cont._group or cont.data._dataset).

As an alternative to the object-oriented approach using DH5File, you can use the functional API provided by the library. This API offers a set of functions for reading and writing data to DH5 files without the need to create file objects. These functions in the respective modules (h5io.cont, h5io.spike, etc.) use the h5py classes as input and output. This is the recommended way if you are familiar with HDF5 and the specification of the DH5 format.

Interactive Data Browser

The dh5browser command provides an interactive graphical viewer for DH5 files with trial navigation:

# Install with browser support
pip install dh5io[browser]

# Open a DH5 file (displays first trial)
dh5browser mydata.dh5

# Open a specific trial
dh5browser mydata.dh5 --trial 2

# Adjust cache size for faster navigation (default: 10)
dh5browser mydata.dh5 --cache-size 20

The browser displays:

• Analog signals (CONT groups) - Multi-channel trace viewer
• Spike trains (SPIKE groups) - Raster plots
• Events (EV02) - Labeled vertical lines in a synchronized viewer
• Epochs (TRIALMAP) - Trial markers

New in latest version: Interactive trial navigation with caching

• Click ◀ Previous / Next ▶ buttons to navigate between trials
• Intelligent LRU caching for instant switching to recently viewed trials
• Configurable cache size to balance memory usage vs. performance
• Debug mode shows cache performance: dh5browser mydata.dh5 --debug

Channel Selection: Double-click on the trace viewer to open the parameters panel where you can:

• Show/hide individual channels by toggling their visible checkbox
• Adjust per-channel gain and offset
• Change channel colors
• All settings automatically persist across sessions

Features include synchronized time navigation, zoom/pan controls, and auto-scaling. The browser is built on ephyviewer and provides an intuitive interface for exploring electrophysiology data.

For more information, see:

• Browser Documentation
• Trial Navigation Guide
• Usage Examples

Developer setup

• Use uv
• Setup pre-push hook for running pytest

  git config --local core.hooksPath .githooks