Skip to content

EasyH5 Toolbox v0.9 (Codename: Daseot - Korean 5)

Latest
Latest
Compare
Choose a tag to compare
@fangq fangq released this 18 Mar 01:35
· 1 commit to master since this release
v0.9
0735b2a

image

EasyH5 Toolbox - An easy-to-use HDF5 data interface (loadh5 and saveh5)

Click here to register and download EasyH5 v0.9

  • Copyright (C) 2019,2022,2025 Qianqian Fang <q.fang at neu.edu>
  • License: GNU General Public License version 3 (GPL v3) or 3-clause BSD license, see LICENSE*.txt
  • Version: 0.9 (code name: Daseot - Korean 5)
  • URL: https://github.com/NeuroJSON/easyh5
  • Compatibility: MATLAB R2010b or newer and GNU Octave 5.0 or newer
  • Acknowledgement: This project is supported by US National Institute of Health (NIH)
    grant U24-NS124027 (NeuroJSON)

ChangeLog

EasyH5 v0.9 (Daseot - Korean 5), FangQ <q.fang (a) neu.edu>

2025-03-16*[4baab54] [feat] initial support of saveh5 using oct-hdf5 in octave
2025-03-16*[a2b62c1] [feat] support Octave low-level HDF5 IO via oct-hdf5
2025-03-15 [1fe742d] [test] pass test on MATLAB R2010b
2025-03-14 [39b3b07] [jsonlab] sync jsonlab with the latest version, update doc
2025-03-13 [e04da0c] [snirf] fix fNIRS/snirf-samples#13
2024-09-15 [2090320] [snirf] allow saving empty 1d vector as timeseries
2024-07-09 [4b4444f] [bug] fix #16, timeseries() can handle complex 1D vector
2024-07-09 [6f145c0] [snirf] fix probe.sourceLabels with timeseries(string({})), fNIRS/snirf-samples#8
2024-07-08*[df03a9c] [feature] use timeseries datatype for true 1d vector, fix #16, fNIRS/snirf-samples#12
2024-07-07 [01e5e53] [bug] allow to store true 1D vector with ndim=1, fix #16, fNIRS/snirf-samples#12
2023-11-26 [a88c2e1] scalar and variablelengthstring can not use with deflate on
2023-11-26 [322b798] reverse forcedim to fix transposed array after roundtrip
2023-11-26 [1c4ad33] sync units from jsonlab
2023-11-26*[b6d102f] automatic format with miss_hit
2023-11-26 [ffd5870] merge scalar and stringarray changes
2023-11-26 [2d38eda] save as scalar instead of length of 1 array
2023-11-26 [830bf24] support octave to load hdf5 file
2023-11-25 [3c8dc14] trim null ending string, transpose string array, octave support
2023-02-12 [e7fc01f] saving and loading string and cell char arrays, fix NeuroJSON/jsnirfy#1
2022-10-01 [172915b] fix sparse matrix saving error, close #14
2022-09-30 [96132b7] fix rootname issue, a regression due to #11, close #13
2022-08-10 [74a430c] Update README.md
2022-08-05*[c1d30f4] can write variable length string via VariableLengthString flag
2022-05-18 [c985103] upgrade all jsonlab files to the latest version, bump to v0.9.0
2022-05-18 [72deacf] allow appending data under 'rootname' path with 'append',1, fix #11, works in MATLAB R2010b
2022-05-18 [a11cc77] set default name, allow saving expressions to /data
2022-04-06 [6ab811a] clear opt to avoid error
2020-05-22 [94b7364] avoid crash in matlab R2014 or earlier when handling attributes
2020-05-15 [dfd1c49] transpose array by default both when saving and loading, fix #10
2020-05-14 [ef1ccdc] fix errors of saving empty matrices on matlab 2014 & older (hdf5 1.8.6)
2020-05-12 [9a1b459] fix regression for complex sparse matices due to #4
2020-05-05 [2951909] add parentheses for test condition, #8
2020-05-05 [600c2d1] fall back to alphabetic order on matlab 2014 and earlier, fix #8
2019-12-14 [e42564d] customizable complex numbers storage
2019-10-25 [1d45bc3] use jdata as input flag
2019-10-25*[a00940e] add jdataencode and jdatadecode functions

Overview

image

EasyH5 is a fully automated, fast, compact and portable MATLAB object to HDF5
exporter/importer. It contains two easy-to-use functions - loadh5.m and
saveh5.m. The saveh5.m can handle almost all MATLAB data types, including
structs, struct arrays, cells, cell arrays, real and complex arrays, strings,
and containers.Map objects. All other data classes (such as a table, digraph,
etc) can also be stored/loaded seemlessly using an undocumented data serialization
interface (MATLAB only).

EasyH5 stores complex-valued arrays using a special compound data type in an
HDF5 dataset. The real-part of the data are stored as Real and the imaginary
part is stored as the Imag component. The loadh5.m automatically converts
such data structure to a complex array. Starting from v0.8, EasyH5 also supports
saving and loading sparse arrays using a compound dataset with 2 or 3
specialized subfields: SparseArray, Real, and, in the case of a sparse
complex array, Imag. The sparse array dimension is stored as an attribute
named SparseArraySize, attached with the dataset. Using the deflate filter
to save compressed arrays is supported in v0.8 and later.

Because HDF5 does not directly support 1-D/N-D cell arrays or struct arrays,
EasyH5 converts these data structures into data groups with names in the
following format

    ['/hdf5/path/.../varname',num2str(idx1d)]

where varname is the variable/field name to the cell/struct array object,
and idx1d is the 1-D integer index of the cell/struct array. We also provide
a function, regrouph5.m to automatically collapse these group/dataset names
into 1-D cell/struct arrays after loading the data using loadh5.m. See examples
below.

Installation

The EasyH5 toolbox can be installed using a single command

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

where the /path/to/easyh5 should be replaced by the unzipped folder
of the toolbox (i.e. the folder containing loadh5.m/saveh5.m).

In v0.8 and newer releases, EasyH5 supports GNU Octave 5.x or later.
In order to use EasyH5 with Octave, one must install a toolbox named oct-hdf5
by running the following command in Octave once

  pkg install https://github.com/fangq/oct-hdf5/archive/refs/heads/main.zip
  pkg load oct-hdf5

EasyH5 supports MATLAB R2010b or newer. However, saveh5 can not save empty
arrays for MATLAB releases before 2015.

Usage

saveh5 - Save a MATLAB struct (array) or cell (array) into an HDF5 file

Save a MATLAB struct (array) or cell (array) into an HDF5 file.

Example:

  a=struct('a',rand(5),'c','string','b',true,'d',2+3i,'e',{'test',[],1:5});
  saveh5(a,'test.h5');
  saveh5(a(1),'test2.h5','rootname','');
  saveh5(a(1),'test2.h5','compression','deflate','compressarraysize',1);
  saveh5('appending data to existing file','test.h5','rootname','/name','append',1);
  saveh5(a,'test.h5j','jdata',1);

loadh5 - Load data in an HDF5 file to a MATLAB structure.

Load data in an HDF5 file to a MATLAB structure.

Example:

  a={rand(2), struct('va',1,'vb','string'), 1+2i};
  saveh5(a,'test.h5');
  a2=loadh5('test.h5')
  a3=loadh5('test.h5','regroup',1)
  isequaln(a,a3.a)
  a4=loadh5('test.h5','/a1')

regrouph5 - Processing an HDF5 based data and group indexed datasets into a cell array

Processing a loadh5 restored data and merge "indexed datasets", whose
names start with an ASCII string followed by a contiguous integer
sequence number starting from 1, into a cell array. For example,
datasets {data.a1, data.a2, data.a3} will be merged into a cell/struct
array data.a with 3 elements.

Example:

  a=struct('a1',rand(5),'a2','string','a3',true,'d',2+3i,'e',{'test',[],1:5});
  a(1).a1=0; a(2).a2='test';
  data=regrouph5(a)
  saveh5(a,'test.h5');
  rawdata=loadh5('test.h5')
  data=regrouph5(rawdata)

Known problems

  • EasyH5 currently does not support 2D cell and struct arrays
  • If a cell name ends with a number, such as a10={...}; regrouph5 can not group the cell correctly
  • If a database/group name is longer than 63 characters, it may have the risk of being truncated
  • When saving a dynamic expression instead of a named variable, the data are stored under path /data

Contribute to EasyH5

Please submit your bug reports, feature requests and questions to the Github Issues page at

https://github.com/NeuroJSON/easyh5/issues

Please feel free to fork our software, making changes, and submit your revision back
to us via "Pull Requests". EasyH5 is open-source and welcome to your contributions!

Assets 2
Loading