EasyH5 - Easy-to-use HDF5 Interface for MATLAB/Octave

EasyH5

Easy-to-use HDF5 data interface for MATLAB and Octave

Version 0.9 MATLAB R2010b+ GNU Octave 5.0+ BSD-3 / GPL v3 NIH Funded

📦 What is EasyH5?

EasyH5 is a fully automated, fast, compact and portable MATLAB/Octave to HDF5 exporter/importer. It contains just two easy-to-use functions: loadh5 and saveh5.

The saveh5 function can handle almost all MATLAB data types, including structs, struct arrays, cells, cell arrays, real and complex arrays, strings, containers.Map objects, and more.

🏆 NeuroJSON Project

EasyH5 is part of the NeuroJSON project (neurojson.org), funded by US NIH grant U24-NS124027. It provides essential HDF5 I/O infrastructure for scientific data storage and exchange.

6+
Years Active
2
Core Functions
100%
Data Coverage
View on GitHub See Examples NeuroJSON

✨ Key Capabilities

  • Fully Automated: Automatic conversion between MATLAB and HDF5 data structures
  • Universal Compatibility: MATLAB R2010b+ and GNU Octave 5.0+
  • Complete Data Support: Handles all MATLAB data types seamlessly
  • Complex & Sparse Arrays: Native support using compound datasets
  • Compression Support: Deflate filter for efficient storage
  • Simple API: Just two functions - loadh5 and saveh5
  • Regrouping: Automatic reconstruction of cell/struct arrays
  • Fast Performance: Optimized for large scientific datasets
View Examples Browse Functions

🔧 Supported Data Types

📊 Arrays

  • Real and complex arrays
  • Sparse matrices (real & complex)
  • Multi-dimensional arrays
  • Logical arrays

🗂️ Containers

  • Structs and struct arrays
  • Cells and cell arrays
  • containers.Map objects
  • Mixed-type collections

📝 Text & Objects

  • Strings and char arrays
  • Tables (MATLAB only)
  • Graphs and digraphs
  • Custom classes (serialized)

🗜️ Special Features

  • Compression with deflate filter
  • Append mode for existing files
  • Custom root paths
  • Empty array handling
See Examples

Why Choose EasyH5?

Simplify your HDF5 workflow

🎯

Simple API

Just two functions: loadh5 and saveh5 - that's all you need

🔄

Full Automation

Automatically handles all MATLAB/Octave data type conversions

🗜️

Compression

Built-in deflate compression for efficient storage

🧮

Complex Data

Native support for complex and sparse arrays using compound types

⚡

High Performance

Optimized for reading and writing large scientific datasets

🔗

Flexible

Append mode, custom paths, and regrouping utilities included

Code Examples

Quick start with EasyH5

% Create sample data
data = struct('matrix', rand(10,10), ...
              'string', 'test', ...
              'cell', {1, 'two', true});

% Save to HDF5 with saveh5
saveh5(data, 'mydata.h5');

% Load from HDF5 with loadh5
loaded = loadh5('mydata.h5');

% Verify data integrity
isequaln(data, loaded.data)
% Save complex data structures with saveh5
a = struct('array', rand(5), ...
           'complex', 2+3i, ...
           'sparse', sparse(eye(5)), ...
           'string', 'test data');

% Basic save
saveh5(a, 'test.h5');

% Save without root name
saveh5(a(1), 'test2.h5', 'rootname', '');

% Save with compression
saveh5(a(1), 'test_compressed.h5', ...
       'compression', 'deflate', ...
       'compressarraysize', 1);

% Append data to existing file
saveh5('new data', 'test.h5', ...
       'rootname', '/newpath', 'append', 1);
% Load HDF5 data with loadh5
a = {rand(2), struct('va', 1, 'vb', 'string'), 1+2i};
saveh5(a, 'test.h5');

% Load entire file
a2 = loadh5('test.h5');

% Load with automatic regrouping
a3 = loadh5('test.h5', 'regroup', 1);

% Verify data matches
isequaln(a, a3.a)

% Load specific path only
a4 = loadh5('test.h5', '/a1');
% regrouph5: Merge indexed datasets into arrays
a = struct('a1', rand(5), ...
           'a2', 'string', ...
           'a3', true, ...
           'd', 2+3i);

% Create struct array
a(1).a1 = 0; 
a(2).a2 = 'test';

% Manual regrouping
data = regrouph5(a)

% Or use 'regroup' option in loadh5
saveh5(a, 'test.h5');
rawdata = loadh5('test.h5');
data = regrouph5(rawdata);

% Or load with automatic regrouping
data = loadh5('test.h5', 'regroup', 1);
% Save with HDF5 deflate compression
data = struct('large_matrix', rand(1000, 1000), ...
              'metadata', 'experiment data');

% Enable compression with deflate filter
saveh5(data, 'compressed.h5', ...
       'compression', 'deflate', ...
       'compressarraysize', 1);

% Set compression level (0-9)
saveh5(data, 'compressed_max.h5', ...
       'compression', 'deflate', ...
       'compresslevel', 9, ...
       'compressarraysize', 1);

% Load compressed file (automatic decompression)
loaded = loadh5('compressed.h5');

Key Features

Everything you need for HDF5 I/O

🎯

Simple Interface

Two functions handle all HDF5 operations - loadh5 and saveh5

🔄

Full Automation

Automatic conversion between MATLAB and HDF5 data structures

🧮

Complex Arrays

Native support for complex-valued arrays using compound types

📊

Sparse Matrices

Efficient storage of sparse arrays with dimensions preserved

🗜️

Compression

Built-in HDF5 deflate compression for smaller file sizes

🔗

Advanced Options

Append mode, custom root paths, and automatic regrouping

Core Functions

Simple and powerful API

Primary Functions

  • saveh5 - Save MATLAB data to HDF5
  • loadh5 - Load HDF5 data to MATLAB
  • regrouph5 - Merge indexed datasets

Data Encoding

  • jdataencode - Encode complex types
  • jdatadecode - Decode JData annotations

Utilities

  • encodevarname - Encode field names
  • decodevarname - Decode field names
  • transposemat - Matrix transposition
  • jsonopt - Option parsing
  • mergestruct - Merge structures
  • varargin2struct - Parse arguments

saveh5 Options

  • 'rootname' - Set root path
  • 'compression' - Enable deflate
  • 'compresslevel' - Set level (0-9)
  • 'compressarraysize' - Min size
  • 'append' - Append to file

loadh5 Options

  • 'regroup' - Auto-regroup arrays
  • 'stringarray' - String handling
  • path - Load specific dataset

Installation

Get started in seconds

📦 MATLAB Installation

Simply add to path:

addpath('/path/to/easyh5');
rehash;

Works with MATLAB R2010b or newer

🐙 Octave Installation

Install oct-hdf5 package first:

pkg install https://github.com/NeuroJSON/...
    oct-hdf5/archive/refs/tags/git20250413.zip
pkg load oct-hdf5

addpath('/path/to/easyh5');

🔧 From GitHub

Clone the repository:

git clone https://github.com/NeuroJSON/easyh5.git
cd easyh5
% In MATLAB/Octave:
addpath(pwd);

📚 Requirements

System requirements:

  • MATLAB R2010b+ (native HDF5 support)
  • Octave 5.0+ with oct-hdf5 package
  • No additional dependencies

Ready to Simplify HDF5?

Fast, automated, and easy to use

6+
Years Development
0.9
Current Version
16
GitHub Stars
Download Latest Release GitHub Repository

Supported by NIH Grant U24-NS124027

BSD-3-Clause or GPL v3 License

Powered by Habitat