2.1.2. Python Examples using h5py

One way to gain a quick familiarity with NeXus is to start working with some data. For at least the first few examples in this section, we have a simple two-column set of 1-D data, collected as part of a series of alignment scans by the APS USAXS instrument during the time it was stationed at beam line 32ID. We will show how to write this data using the Python language and the h5py package 1 (using h5py calls directly rather than using the NeXus NAPI). The actual data to be written was extracted (elsewhere) from a spec 2 data file and read as a text block from a file by the Python source code. Our examples will start with the simplest case and add only mild complexity with each new case since these examples are meant for those who are unfamiliar with NeXus.

1

h5py: https://www.h5py.org/

2

SPEC: http://certif.com/spec.html

The data shown plotted in the next figure will be written to the NeXus HDF5 file using only two NeXus base classes, NXentry and NXdata, in the first example and then minor variations on this structure in the next two examples. The data model is identical to the one in the Introduction chapter except that the names will be different, as shown below:

simple data structure

data structure, (from Introduction)

our h5py example

1/entry:NXentry
2    /mr_scan:NXdata
3       /mr : float64[31]
4       /I00 : int32[31]
Example-H5py-Plot

plot of our mr_scan

two-column data for our mr_scan

 117.92608    1037
 217.92591    1318
 317.92575    1704
 417.92558    2857
 517.92541    4516
 617.92525    9998
 717.92508    23819
 817.92491    31662
 917.92475    40458
1017.92458    49087
1117.92441    56514
1217.92425    63499
1317.92408    66802
1417.92391    66863
1517.92375    66599
1617.92358    66206
1717.92341    65747
1817.92325    65250
1917.92308    64129
2017.92291    63044
2117.92275    60796
2217.92258    56795
2317.92241    51550
2417.92225    43710
2517.92208    29315
2617.92191    19782
2717.92175    12992
2817.92158    6622
2917.92141    4198
3017.92125    2248
3117.92108    1321

2.1.2.1. Writing the simplest data using h5py

These two examples show how to write the simplest data (above). One example writes the data directly to the NXdata group while the other example writes the data to NXinstrument/NXdetector/data and then creates a soft link to that data in NXdata.

2.1.2.2. Complete h5py example writing and reading a NeXus data file

Writing the HDF5 file using h5py

In the main code section of BasicWriter.py, a current time stamp is written in the format of ISO 8601 (yyyy-mm-ddTHH:MM:SS). For simplicity of this code example, we use a text string for the time, rather than computing it directly from Python support library calls. It is easier this way to see the exact type of string formatting for the time. When using the Python datetime package, one way to write the time stamp is:

1timestamp = "T".join( str( datetime.datetime.now() ).split() )

The data (mr is similar to “two_theta” and I00 is similar to “counts”) is collated into two Python lists. We use the numpy package to read the file and parse the two-column format.

The new HDF5 file is opened (and created if not already existing) for writing, setting common NeXus attributes in the same command from our support library. Proper HDF5+NeXus groups are created for /entry:NXentry/mr_scan:NXdata. Since we are not using the NAPI, our support library must create and set the NX_class attribute on each group.

Note

We want to create the desired structure of /entry:NXentry/mr_scan:NXdata/.

  1. First, our support library calls f = h5py.File() to create the file and root level NeXus structure.

  2. Then, it calls nxentry = f.create_group("entry") to create the NXentry group called entry at the root level.

  3. Then, it calls nxdata = nxentry.create_group("mr_scan") to create the NXentry group called entry as a child of the NXentry group.

Next, we create a dataset called title to hold a title string that can appear on the default plot.

Next, we create datasets for mr and I00 using our support library. The data type of each, as represented in numpy, will be recognized by h5py and automatically converted to the proper HDF5 type in the file. A Python dictionary of attributes is given, specifying the engineering units and other values needed by NeXus to provide a default plot of this data. By setting signal="I00" as an attribute on the group, NeXus recognizes I00 as the default y axis for the plot. The axes="mr" attribute on the NXdata group connects the dataset to be used as the x axis.

Finally, we must remember to call f.close() or we might corrupt the file when the program quits.

BasicWriter.py: Write a NeXus HDF5 file using Python with h5py

 1#!/usr/bin/env python
 2'''Writes a NeXus HDF5 file using h5py and numpy'''
 3
 4import h5py    # HDF5 support
 5import numpy
 6import six
 7
 8print("Write a NeXus HDF5 file")
 9fileName = u"prj_test.nexus.hdf5"
10timestamp = u"2010-10-18T17:17:04-0500"
11
12# load data from two column format
13data = numpy.loadtxt(u"input.dat").T
14mr_arr = data[0]
15i00_arr = numpy.asarray(data[1],'int32')
16
17# create the HDF5 NeXus file
18f = h5py.File(fileName, "w")
19# point to the default data to be plotted
20f.attrs[u'default']          = u'entry'
21# give the HDF5 root some more attributes
22f.attrs[u'file_name']        = fileName
23f.attrs[u'file_time']        = timestamp
24f.attrs[u'instrument']       = u'APS USAXS at 32ID-B'
25f.attrs[u'creator']          = u'BasicWriter.py'
26f.attrs[u'NeXus_version']    = u'4.3.0'
27f.attrs[u'HDF5_Version']     = six.u(h5py.version.hdf5_version)
28f.attrs[u'h5py_version']     = six.u(h5py.version.version)
29
30# create the NXentry group
31nxentry = f.create_group(u'entry')
32nxentry.attrs[u'NX_class'] = u'NXentry'
33nxentry.attrs[u'default'] = u'mr_scan'
34nxentry.create_dataset(u'title', data=u'1-D scan of I00 v. mr')
35
36# create the NXentry group
37nxdata = nxentry.create_group(u'mr_scan')
38nxdata.attrs[u'NX_class'] = u'NXdata'
39nxdata.attrs[u'signal'] = u'I00'      # Y axis of default plot
40nxdata.attrs[u'axes'] = u'mr'         # X axis of default plot
41nxdata.attrs[u'mr_indices'] = [0,]   # use "mr" as the first dimension of I00
42
43# X axis data
44ds = nxdata.create_dataset(u'mr', data=mr_arr)
45ds.attrs[u'units'] = u'degrees'
46ds.attrs[u'long_name'] = u'USAXS mr (degrees)'    # suggested X axis plot label
47
48# Y axis data
49ds = nxdata.create_dataset(u'I00', data=i00_arr)
50ds.attrs[u'units'] = u'counts'
51ds.attrs[u'long_name'] = u'USAXS I00 (counts)'    # suggested Y axis plot label
52
53f.close()   # be CERTAIN to close the file
54
55print("wrote file:", fileName)

Reading the HDF5 file using h5py

The file reader, BasicReader.py, is very simple since the bulk of the work is done by h5py. Our code opens the HDF5 we wrote above, prints the HDF5 attributes from the file, reads the two datasets, and then prints them out as columns. As simple as that. Of course, real code might add some error-handling and extracting other useful stuff from the file.

Note

See that we identified each of the two datasets using HDF5 absolute path references (just using the group and dataset names). Also, while coding this example, we were reminded that HDF5 is sensitive to upper or lowercase. That is, I00 is not the same is i00.

BasicReader.py: Read a NeXus HDF5 file using Python with h5py

 1#!/usr/bin/env python
 2'''Reads NeXus HDF5 files using h5py and prints the contents'''
 3
 4import h5py    # HDF5 support
 5
 6fileName = "prj_test.nexus.hdf5"
 7f = h5py.File(fileName,  "r")
 8for item in f.attrs.keys():
 9    print(item + ":", f.attrs[item])
10mr = f['/entry/mr_scan/mr']
11i00 = f['/entry/mr_scan/I00']
12print("%s\t%s\t%s" % ("#", "mr", "I00"))
13for i in range(len(mr)):
14    print("%d\t%g\t%d" % (i, mr[i], i00[i]))
15f.close()

Output from BasicReader.py is shown next.

Output from BasicReader.py

 1file_name: prj_test.nexus.hdf5
 2file_time: 2010-10-18T17:17:04-0500
 3creator: BasicWriter.py
 4HDF5_Version: 1.8.5
 5NeXus_version: 4.3.0
 6h5py_version: 1.2.1
 7instrument: APS USAXS at 32ID-B
 8#   mr  I00
 90   17.9261 1037
101   17.9259 1318
112   17.9258 1704
123   17.9256 2857
134   17.9254 4516
145   17.9252 9998
156   17.9251 23819
167   17.9249 31662
178   17.9247 40458
189   17.9246 49087
1910  17.9244 56514
2011  17.9243 63499
2112  17.9241 66802
2213  17.9239 66863
2314  17.9237 66599
2415  17.9236 66206
2516  17.9234 65747
2617  17.9232 65250
2718  17.9231 64129
2819  17.9229 63044
2920  17.9228 60796
3021  17.9226 56795
3122  17.9224 51550
3223  17.9222 43710
3324  17.9221 29315
3425  17.9219 19782
3526  17.9217 12992
3627  17.9216 6622
3728  17.9214 4198
3829  17.9213 2248
3930  17.9211 1321

Finding the default plottable data

Let’s make a new reader that follows the chain of attributes (@default, @signal, and @axes) to find the default plottable data. We’ll use the same data file as the previous example. Our demo here assumes one-dimensional data. (For higher dimensionality data, we’ll need more complexity when handling the @axes attribute and we’ll to check the field sizes. See section Find the plottable data, subsection Version 3, for the details.)

reader_attributes_trail.py: Read a NeXus HDF5 file using Python with h5py

 1
 2import h5py
 3
 4with h5py.File("prj_test.nexus.hdf5", "r") as nx:
 5    # find the default NXentry group
 6    nx_entry = nx[nx.attrs["default"]]
 7    # find the default NXdata group
 8    nx_data = nx_entry[nx_entry.attrs["default"]]
 9    # find the signal field
10    signal = nx_data[nx_data.attrs["signal"]]
11    # find the axes field(s)
12    attr_axes = nx_data.attrs["axes"]
13    if isinstance(attr_axes, (set, tuple, list)):
14        #  but check that attr_axes only describes 1-D data
15        if len(attr_axes) == 1:
16            attr_axes = attr_axes[0]
17        else:
18            raise ValueError(f"expected 1-D data but @axes={attr_axes}")
19    axes = nx_data[attr_axes]
20
21    print(f"file: {nx.filename}")
22    print(f"signal: {signal.name}")
23    print(f"axes: {axes.name}")
24    print(f"{axes.name} {signal.name}")
25    for x, y in zip(axes, signal):
26        print(x, y)

Output from reader_attributes_trail.py is shown next.

Output from reader_attributes_trail.py

 1file: prj_test.nexus.hdf5
 2signal: /entry/mr_scan/I00
 3axes: /entry/mr_scan/mr
 4/entry/mr_scan/mr /entry/mr_scan/I00
 517.92608 1037
 617.92591 1318
 717.92575 1704
 817.92558 2857
 917.92541 4516
1017.92525 9998
1117.92508 23819
1217.92491 31662
1317.92475 40458
1417.92458 49087
1517.92441 56514
1617.92425 63499
1717.92408 66802
1817.92391 66863
1917.92375 66599
2017.92358 66206
2117.92341 65747
2217.92325 65250
2317.92308 64129
2417.92291 63044
2517.92275 60796
2617.92258 56795
2717.92241 51550
2817.92225 43710
2917.92208 29315
3017.92191 19782
3117.92175 12992
3217.92158 6622
3317.92141 4198
3417.92125 2248
3517.92108 1321

Plotting the HDF5 file

Now that we are certain our file conforms to the NeXus standard, let’s plot it using the NeXpy 3 client tool. To help label the plot, we added the long_name attributes to each of our datasets. We also added metadata to the root level of our HDF5 file similar to that written by the NAPI. It seemed to be a useful addition. Compare this with plot of our mr_scan and note that the horizontal axis of this plot is mirrored from that above. This is because the data is stored in the file in descending mr order and NeXpy has plotted it that way (in order of appearance) by default.

3

NeXpy: http://nexpy.github.io/nexpy/

fig-Example-H5py-nexpy-plot

plot of our mr_scan using NeXpy