2.1.3. HDF5 in MATLAB

author:

Paul Kienzle, NIST

Note

Editor’s Note: These files were copied directly from an older version of the NeXus documentation (DocBook) and have not been checked that they will run under current Matlab versions.

2.1.3.1. input.dat

This is the same data used with HDF5 in Python.

 1 17.92608    1037
 2 17.92591    1318
 3 17.92575    1704
 4 17.92558    2857
 5 17.92541    4516
 6 17.92525    9998
 7 17.92508    23819
 8 17.92491    31662
 9 17.92475    40458
10 17.92458    49087
11 17.92441    56514
12 17.92425    63499
13 17.92408    66802
14 17.92391    66863
15 17.92375    66599
16 17.92358    66206
17 17.92341    65747
18 17.92325    65250
19 17.92308    64129
20 17.92291    63044
21 17.92275    60796
22 17.92258    56795
23 17.92241    51550
24 17.92225    43710
25 17.92208    29315
26 17.92191    19782
27 17.92175    12992
28 17.92158    6622
29 17.92141    4198
30 17.92125    2248
31 17.92108    1321

2.1.3.2. writing data

basic_writer.m: Write a NeXus HDF5 file using Matlab

 1 % Writes a NeXus HDF5 file using matlab
 2 
 3 disp 'Write a NeXus HDF5 file'
 4 filename = 'prj_test.nexus.hdf5';
 5 timestamp = '2010-10-18T17:17:04-0500';
 6 
 7 % read input data
 8 A = load('input.dat');
 9 mr = A(:,1);
10 I00 = int32(A(:,2));
11 
12 % clear out old file, if it exists
13 
14 delete(filename);
15 
16 % using the simple h5 interface, there is no way to create a group without
17 % first creating a dataset; creating the dataset creates all intervening
18 % groups.
19 
20 % store x
21 h5create(filename,'/entry/mr_scan/mr',[length(mr)]);
22 h5write(filename,'/entry/mr_scan/mr',mr);
23 h5writeatt(filename,'/entry/mr_scan/mr','units','degrees');
24 h5writeatt(filename,'/entry/mr_scan/mr','long_name','USAXS mr (degrees)');
25 
26 % store y
27 h5create(filename,'/entry/mr_scan/I00',[length(I00)],'DataType','int32');
28 h5write(filename,'/entry/mr_scan/I00',I00);
29 h5writeatt(filename,'/entry/mr_scan/I00','units','counts');
30 h5writeatt(filename,'/entry/mr_scan/I00','long_name','USAXS I00 (counts)');
31 
32 % indicate that we are plotting y vs. x
33 h5writeatt(filename,'/','default','entry');
34 h5writeatt(filename,'/entry','default','mr_scan');
35 h5writeatt(filename,'/entry/mr_scan','signal','I00');
36 h5writeatt(filename,'/entry/mr_scan','axes','mr_scan');
37 h5writeatt(filename,'/entry/mr_scan','mr_scan_indices', int32(0));
38 
39 % add NeXus metadata
40 h5writeatt(filename,'/','file_name',filename);
41 h5writeatt(filename,'/','file_time',timestamp);
42 h5writeatt(filename,'/','instrument','APS USAXS at 32ID-B');
43 h5writeatt(filename,'/','creator','basic_writer.m');
44 h5writeatt(filename,'/','NeXus_version','4.3.0');
45 h5writeatt(filename,'/','HDF5_Version','1.6'); % no 1.8 features used in this example
46 h5writeatt(filename,'/entry','NX_class','NXentry');
47 h5writeatt(filename,'/entry/mr_scan','NX_class','NXdata');
48 
49 
50 h5disp(filename);

2.1.3.3. reading data

basic_reader.m: Read a NeXus HDF5 file using Matlab

 1 % Reads NeXus HDF5 file and print the contents
 2 
 3 filename = 'prj_test.nexus.hdf5';
 4 root = h5info(filename,'/');
 5 attrs = root.Attributes;
 6 for i = 1:length(attrs)
 7     fprintf('%s: %s\n', attrs(i).Name, attrs(i).Value);
 8 end
 9 mr = h5read(filename,'/entry/mr_scan/mr');
10 i00 = h5read(filename, '/entry/mr_scan/I00');
11 fprintf('#\t%s\t%s\n','mr','I00');
12 for i = 1:length(mr)
13     fprintf('%d\t%g\t%d\n', i, mr(i), i00(i));
14 end

2.1.3.4. writing data file with links

writer_2_1.m: Write a NeXus HDF5 file with links

 1 % Writes a simple NeXus HDF5 file with links
 2 % according to the example from Figure 2.1 in the Design chapter
 3 
 4 filename = 'writer_2_1.hdf5';
 5 
 6 % read input data
 7 A = load('input.dat');
 8 two_theta = A(:,1);
 9 counts = int32(A(:,2));
10 
11 % clear out old file, if it exists
12 delete(filename);
13 
14 % store x
15 h5create(filename,'/entry/instrument/detector/two_theta',[length(two_theta)]);
16 h5write(filename,'/entry/instrument/detector/two_theta',two_theta);
17 h5writeatt(filename,'/entry/instrument/detector/two_theta','units','degrees');
18 
19 % store y
20 h5create(filename,'/entry/instrument/detector/counts',[length(counts)],'DataType','int32');
21 h5write(filename,'/entry/instrument/detector/counts',counts);
22 h5writeatt(filename,'/entry/instrument/detector/counts','units','counts');
23 
24 % create group NXdata with links to detector
25 % note: requires the additional file h5link.m
26 h5link(filename,'/entry/instrument/detector/two_theta','/entry/data/two_theta');
27 h5link(filename,'/entry/instrument/detector/counts','/entry/data/counts');
28 
29 % indicate that we are plotting y vs. x
30 h5writeatt(filename,'/','default','entry');
31 h5writeatt(filename,'/entry','default','data');
32 h5writeatt(filename,'/entry/data','signal','counts');
33 h5writeatt(filename,'/entry/data','axes','two_theta');
34 h5writeatt(filename,'/entry/data','two_theta_indices',int32(0));
35 
36 % add NeXus metadata
37 h5writeatt(filename,'/','file_name',filename);
38 h5writeatt(filename,'/','file_time',timestamp);
39 h5writeatt(filename,'/','instrument','APS USAXS at 32ID-B');
40 h5writeatt(filename,'/','creator','writer_2_1.m');
41 h5writeatt(filename,'/','NeXus_version','4.3.0');
42 h5writeatt(filename,'/','HDF5_Version','1.6'); % no 1.8 features used in this example
43 h5writeatt(filename,'/entry','NX_class','NXentry');
44 h5writeatt(filename,'/entry/instrument','NX_class','NXinstrument');
45 h5writeatt(filename,'/entry/instrument/detector','NX_class','NXdetector');
46 h5writeatt(filename,'/entry/data','NX_class','NXdata');
47 
48 % show structure of the file that was created
49 h5disp(filename);

h5link.m: support module for creating NeXus-style HDF5 hard links

 1 function h5link(filename, from, to)
 2 %H5LINK Create link to an HDF5 dataset.
 3 %   H5LINK(FILENAME,SOURCE,TARGET) creates an HDF5 link from the
 4 %   dataset at location SOURCE to a dataset at location TARGET.  All
 5 %   intermediate groups in the path to target are created.
 6 %
 7 %   Example:  create a link from /hello/world to /goodbye/world
 8 %      h5create('myfile.h5','/hello/world',[100 200]);
 9 %      h5link('myfile.h5','/hello/world','/goodbye/world');
10 %      hgdisp('myfile.h5');
11 %
12 %   See also: h5create, h5read, h5write, h5info, h5disp
13 
14 % split from and to into group/dataset
15 idx = strfind(from,'/');
16 from_path = from(1:idx(end)-1);
17 from_data = from(idx(end)+1:end);
18 idx = strfind(to,'/');
19 to_path = to(1:idx(end)-1);
20 to_data = to(idx(end)+1:end);
21   
22 % open the HDF file
23 fid = H5F.open(filename,'H5F_ACC_RDWR','H5P_DEFAULT');
24   
25 % create target group if it doesn't already exist
26 create_intermediate = H5P.create('H5P_LINK_CREATE');
27 H5P.set_create_intermediate_group(create_intermediate, 1);
28 try
29     H5G.create(fid,to_path,create_intermediate,'H5P_DEFAULT','H5P_DEFAULT');
30 catch
31 end
32 H5P.close(create_intermediate);
33 
34 % open groups and create link
35 from_id = H5G.open(fid, from_path);
36 to_id = H5G.open(fid, to_path);
37 H5L.create_hard(from_id, from_data, to_id, to_data, 'H5P_DEFAULT','H5P_DEFAULT');
38 
39 % close all
40 H5G.close(from_id);
41 H5G.close(to_id);
42 H5F.close(fid);
43 end

2.1.3.5. Downloads

file	description
input.dat	two-column text data file, also used in other examples
basic_writer.m	writes a NeXus HDF5 file using input.dat
basic_reader.m	reads the NeXus HDF5 file written by basic_writer.m
h5link.m	support module for creating NeXus-style HDF5 hard links
writer_2_1.m	like basic_writer.m but stores data in /entry/instrument/detector and then links to NXdata group