h5py example writing the simplest NeXus data file

In this example, the 1-D scan data will be written into the simplest possible NeXus HDF5 data file, containing only the required NeXus components. NeXus requires at least one NXentry group at the root level of an HDF5 file. The NXentry group contains all the data and associated information that comprise a single measurement. NXdata is used to describe the plottable data in the NXentry group. The simplest place to store data in a NeXus file is directly in the NXdata group, as shown in the next figure.

fig.simple-example-h5py

Simple Example

In the above figure, the data file (writer_1_3_h5py.hdf5) contains a hierarchy of items, starting with an NXentry named entry. (The full HDF5 path reference, /entry in this case, is shown to the right of each component in the data structure.) The next h5py code example will show how to build an HDF5 data file with this structure. Starting with the numerical data described above, the only information written to the file is the absolute minimum information NeXus requires. In this example, you can see how the HDF5 file is created, how Groups and datasets (Fields) are created, and how Attributes are assigned. Note particularly the NX_class attribute on each HDF5 group that describes which of the NeXus Base Class Definitions is being used. When the next Python program (writer_1_3_h5py.py) is run from the command line (and there are no problems), the writer_1_3_h5py.hdf5 file is generated.

 1#!/usr/bin/env python
 2'''
 3Writes the simplest NeXus HDF5 file using h5py 
 4
 5Uses method accepted at 2014NIAC
 6according to the example from Figure 1.3 
 7in the Introduction chapter
 8'''
 9
10import h5py
11import numpy
12
13buffer = numpy.loadtxt("input.dat").T
14tthData = buffer[0]                             # float[]
15countsData = numpy.asarray(buffer[1],'int32')   # int[]
16
17f = h5py.File("writer_1_3.hdf5", "w")  # create the HDF5 NeXus file
18# since this is a simple example, no attributes are used at this point
19
20nxentry = f.create_group(u"Scan")
21nxentry.attrs[u"NX_class"] = u"NXentry"
22
23nxdata = nxentry.create_group(u"data")
24nxdata.attrs["NX_class"] = u"NXdata"
25nxdata.attrs[u"signal"] = u"counts"
26nxdata.attrs[u"axes"] = u"two_theta"
27nxdata.attrs[u"two_theta_indices"] = [0,]
28
29tth = nxdata.create_dataset(u"two_theta", data=tthData)
30tth.attrs[u"units"] = u"degrees"
31
32counts = nxdata.create_dataset(u"counts", data=countsData)
33counts.attrs[u"units"] = u"counts"
34
35f.close()   # be CERTAIN to close the file

One of the tools provided with the HDF5 support libraries is the h5dump command, a command-line tool to print out the contents of an HDF5 data file. With no better tool in place (the output is verbose), this is a good tool to investigate what has been written to the HDF5 file. View this output from the command line using h5dump writer_1_3.hdf5. Compare the data contents with the numbers shown above. Note that the various HDF5 data types have all been decided by the h5py support package.

Note

The only difference between this file and one written using the NAPI is that the NAPI file will have some additional, optional attributes set at the root level of the file that tells the original file name, time it was written, and some version information about the software involved.

Since the output of h5dump is verbose (see the Downloads section below), the punx tree tool 1 was used to print out the structure of HDF5 data files. This tool provides a simplified view of the NeXus file. Here is the output:

 1writer_1_3.hdf5
 2  Scan:NXentry
 3    @NX_class = NXentry
 4    data:NXdata
 5      @NX_class = NXdata
 6      @signal = "counts"
 7      @axes = "two_theta"
 8      @two_theta_indices = [0]
 9      counts:int32[31] = [1037, 1318, 1704, '...', 1321]
10        @units = "counts"
11      two_theta:float64[31] = [17.926079999999999, 17.925909999999998, 17.925750000000001, '...', 17.92108]
12        @units = "degrees"

As the data files in these examples become more complex, you will appreciate the information density provided by punx tree.

1

punx tree : https://punx.readthedocs.io/en/latest/source_code/h5tree.html#how-to-use-h5tree

downloads

The Python code and files related to this section may be downloaded from the following table.

file

description

writer_1_3.py

python code to write example writer_1_3

writer_1_3.hdf5

NeXus file written by this code

writer_1_3_h5dump.txt

h5dump analysis of the NeXus file

writer_1_3_structure.txt

punx tree analysis of the NeXus file