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 "all the data and associated information that comprise a single measurement." NeXus also requires that each NXentry group must contain at least one NXdata group. 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.

Figure 4.2. 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 Data Groups and datasets (Data Fields) are created, and how Data Attributes are assigned. Note particularly the NX_class attribute on each HDF5 group that describes which of the NeXus Base Classes 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.

#!/usr/bin/env python
'''
Writes the simplest NeXus HDF5 file using h5py
according to the example from Figure 1.3 
in the Introduction chapter
'''

import h5py
import numpy

INPUT_FILE = 'input.dat'
HDF5_FILE = 'writer_1_3_h5py.hdf5'

#---------------------------

tthData, countsData = numpy.loadtxt(INPUT_FILE).T

f = h5py.File(HDF5_FILE, "w")  # create the HDF5 NeXus file
# since this is a simple example, no attributes are used at this point

nxentry = f.create_group('Scan')
nxentry.attrs["NX_class"] = 'NXentry'

nxdata = nxentry.create_group('data')
nxdata.attrs["NX_class"] = 'NXdata'

tth = nxdata.create_dataset("two_theta", data=tthData)
tth.attrs['units'] = "degrees"

counts = nxdata.create_dataset("counts", data=countsData)
counts.attrs['units'] = "counts"
counts.attrs['signal'] = "1"
counts.attrs['axes'] = "two_theta"

f.close()	# be CERTAIN to close the file

We wish to make things a bit simpler for ourselves when creating the common structures we use in our data files. To help, we gather together some of the common concepts such as create a file, create a NeXus group, create a dataset and start to build a helper library. (See mylib support module for more details.) Here, we call it my_lib. Applying it to the simple example above, our code only becomes a couple lines shorter! (Let's hope the library starts to help in larger or more complicated projects.) Here's the revision that replaces direct calls to numpy and h5py with calls to our library. It generates the file writer_1_3.hdf5.

#!/usr/bin/env python
'''
Writes the simplest NeXus HDF5 file using 
a simple helper library with h5py and numpy calls
according to the example from Figure 1.3 
in the Introduction chapter
'''

import my_lib

INPUT_FILE = 'input.dat'
HDF5_FILE = 'writer_1_3.hdf5'

#---------------------------

tthData, countsData = my_lib.get_2column_data(INPUT_FILE)

f = my_lib.makeFile(HDF5_FILE)
# since this is a simple example, no attributes are used at this point

nxentry = my_lib.makeGroup(f, 'Scan', 'NXentry')
nxdata = my_lib.makeGroup(nxentry, 'data', 'NXdata')

my_lib.makeDataset(nxdata, "two_theta", tthData, units='degrees')
my_lib.makeDataset(nxdata, "counts", countsData, 
                   units='counts', signal='1', axes='two_theta')

f.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.

HDF5 "writer_1_3.hdf5" {
GROUP "/" {
   GROUP "Scan" {
      ATTRIBUTE "NX_class" {
         DATATYPE  H5T_STRING {
               STRSIZE 7;
               STRPAD H5T_STR_NULLPAD;
               CSET H5T_CSET_ASCII;
               CTYPE H5T_C_S1;
            }
         DATASPACE  SCALAR
         DATA {
         (0): "NXentry"
         }
      }
      GROUP "data" {
         ATTRIBUTE "NX_class" {
            DATATYPE  H5T_STRING {
                  STRSIZE 6;
                  STRPAD H5T_STR_NULLPAD;
                  CSET H5T_CSET_ASCII;
                  CTYPE H5T_C_S1;
               }
            DATASPACE  SCALAR
            DATA {
            (0): "NXdata"
            }
         }
         DATASET "counts" {
            DATATYPE  H5T_STD_I32LE
            DATASPACE  SIMPLE { ( 31 ) / ( 31 ) }
            DATA {
            (0): 1037, 1318, 1704, 2857, 4516, 9998, 23819, 31662, 40458,
            (9): 49087, 56514, 63499, 66802, 66863, 66599, 66206, 65747,
            (17): 65250, 64129, 63044, 60796, 56795, 51550, 43710, 29315,
            (25): 19782, 12992, 6622, 4198, 2248, 1321
            }
            ATTRIBUTE "units" {
               DATATYPE  H5T_STRING {
                     STRSIZE 6;
                     STRPAD H5T_STR_NULLPAD;
                     CSET H5T_CSET_ASCII;
                     CTYPE H5T_C_S1;
                  }
               DATASPACE  SCALAR
               DATA {
               (0): "counts"
               }
            }
            ATTRIBUTE "signal" {
               DATATYPE  H5T_STRING {
                     STRSIZE 1;
                     STRPAD H5T_STR_NULLPAD;
                     CSET H5T_CSET_ASCII;
                     CTYPE H5T_C_S1;
                  }
               DATASPACE  SCALAR
               DATA {
               (0): "1"
               }
            }
            ATTRIBUTE "axes" {
               DATATYPE  H5T_STRING {
                     STRSIZE 9;
                     STRPAD H5T_STR_NULLPAD;
                     CSET H5T_CSET_ASCII;
                     CTYPE H5T_C_S1;
                  }
               DATASPACE  SCALAR
               DATA {
               (0): "two_theta"
               }
            }
         }
         DATASET "two_theta" {
            DATATYPE  H5T_IEEE_F64LE
            DATASPACE  SIMPLE { ( 31 ) / ( 31 ) }
            DATA {
            (0): 17.9261, 17.9259, 17.9258, 17.9256, 17.9254, 17.9252,
            (6): 17.9251, 17.9249, 17.9247, 17.9246, 17.9244, 17.9243,
            (12): 17.9241, 17.9239, 17.9237, 17.9236, 17.9234, 17.9232,
            (18): 17.9231, 17.9229, 17.9228, 17.9226, 17.9224, 17.9222,
            (24): 17.9221, 17.9219, 17.9217, 17.9216, 17.9214, 17.9213,
            (30): 17.9211
            }
            ATTRIBUTE "units" {
               DATATYPE  H5T_STRING {
                     STRSIZE 7;
                     STRPAD H5T_STR_NULLPAD;
                     CSET H5T_CSET_ASCII;
                     CTYPE H5T_C_S1;
                  }
               DATASPACE  SCALAR
               DATA {
               (0): "degrees"
               }
            }
         }
      }
   }
}
}

Since the output of h5dump is verbose, a tool (see h5toText support module) was created to print out the structure of HDF5 data files. This tool provides a simplified view of the NeXus file. It is run with a command like this: python h5toText.py h5dump writer_1_3.hdf5. Here is the output:

writer_1_3.hdf5:NeXus data file
  Scan:NXentry
    @NX_class = NXentry
    data:NXdata
      @NX_class = NXdata
      counts:NX_INT32[31] = __array
        @units = counts
        @signal = 1
        @axes = two_theta
        __array = [1037, 1318, 1704, '...', 1321]
      two_theta:NX_FLOAT64[31] = __array
        @units = degrees
        __array = [17.926079999999999, 17.925909999999998, 17.925750000000001, '...', 17.92108]

As the data files in these examples become more complex, you will appreciate the information density provided by the h5toText.py tool.

Building on the previous example, we wish to identify our measured data with the detector on the instrument where it was generated. In this hypothetical case, since the detector was positioned at some angle two_theta, we choose to store both datasets, two_theta and counts, in a NeXus group. One appropriate NeXus group is NXdetector. This group is placed in a NXinstrument group which is placed in a NXentry group. Still, NeXus requires a NXdata group. Rather than duplicate the same data already placed in the detector group, we choose to link to those datasets from the NXdata group. (Compare the next figure with simple example showing data linking in the NeXus Design chapter of the NeXus User Manual.) The NeXus Design chapter provides a figure (simple example showing data linking) with a small variation from our previous example, placing the measured data within the /entry/instrument/detector group. Links are made from that data to the /entry/data group.

Figure 4.3. h5py example showing linking in a NeXus file

The Python code to build an HDF5 data file with that structure (using numerical data from the previous example) is shown below.

#!/usr/bin/env python
'''
Writes a simple NeXus HDF5 file using h5py with links
according to the example from Figure 2.1 in the Design chapter
'''

import my_lib

INPUT_FILE = 'input.dat'
HDF5_FILE = 'writer_2_1.hdf5'

#---------------------------

tthData, countsData = my_lib.get_2column_data(INPUT_FILE)

f = my_lib.makeFile(HDF5_FILE)  # create the HDF5 NeXus file

nxentry = my_lib.makeGroup(f, 'entry', 'NXentry')
nxinstrument = my_lib.makeGroup(nxentry, 'instrument', 'NXinstrument')
nxdetector = my_lib.makeGroup(nxinstrument, 'detector', 'NXdetector')

tth = my_lib.makeDataset(nxdetector, "two_theta", tthData, units='degrees')
counts = my_lib.makeDataset(nxdetector, "counts", countsData, 
                   units='counts', signal='1', axes='two_theta')

nxdata = my_lib.makeGroup(nxentry, 'data', 'NXdata')
my_lib.makeLink(nxdetector, tth, nxdata.name+'/two_theta')
my_lib.makeLink(nxdetector, counts, nxdata.name+'/counts')

f.close()	# be CERTAIN to close the file

It is interesting to compare the output of the h5dump of the data file writer_2_1.hdf5 with our Python instructions.

HDF5 "writer_2_1.hdf5" {
GROUP "/" {
   GROUP "entry" {
      ATTRIBUTE "NX_class" {
         DATATYPE  H5T_STRING {
               STRSIZE 7;
               STRPAD H5T_STR_NULLPAD;
               CSET H5T_CSET_ASCII;
               CTYPE H5T_C_S1;
            }
         DATASPACE  SCALAR
         DATA {
         (0): "NXentry"
         }
      }
      GROUP "data" {
         ATTRIBUTE "NX_class" {
            DATATYPE  H5T_STRING {
                  STRSIZE 6;
                  STRPAD H5T_STR_NULLPAD;
                  CSET H5T_CSET_ASCII;
                  CTYPE H5T_C_S1;
               }
            DATASPACE  SCALAR
            DATA {
            (0): "NXdata"
            }
         }
         DATASET "counts" {
            DATATYPE  H5T_STD_I32LE
            DATASPACE  SIMPLE { ( 31 ) / ( 31 ) }
            DATA {
            (0): 1037, 1318, 1704, 2857, 4516, 9998, 23819, 31662, 40458,
            (9): 49087, 56514, 63499, 66802, 66863, 66599, 66206, 65747,
            (17): 65250, 64129, 63044, 60796, 56795, 51550, 43710, 29315,
            (25): 19782, 12992, 6622, 4198, 2248, 1321
            }
            ATTRIBUTE "units" {
               DATATYPE  H5T_STRING {
                     STRSIZE 6;
                     STRPAD H5T_STR_NULLPAD;
                     CSET H5T_CSET_ASCII;
                     CTYPE H5T_C_S1;
                  }
               DATASPACE  SCALAR
               DATA {
               (0): "counts"
               }
            }
            ATTRIBUTE "signal" {
               DATATYPE  H5T_STRING {
                     STRSIZE 1;
                     STRPAD H5T_STR_NULLPAD;
                     CSET H5T_CSET_ASCII;
                     CTYPE H5T_C_S1;
                  }
               DATASPACE  SCALAR
               DATA {
               (0): "1"
               }
            }
            ATTRIBUTE "axes" {
               DATATYPE  H5T_STRING {
                     STRSIZE 9;
                     STRPAD H5T_STR_NULLPAD;
                     CSET H5T_CSET_ASCII;
                     CTYPE H5T_C_S1;
                  }
               DATASPACE  SCALAR
               DATA {
               (0): "two_theta"
               }
            }
            ATTRIBUTE "target" {
               DATATYPE  H5T_STRING {
                     STRSIZE 33;
                     STRPAD H5T_STR_NULLPAD;
                     CSET H5T_CSET_ASCII;
                     CTYPE H5T_C_S1;
                  }
               DATASPACE  SCALAR
               DATA {
               (0): "/entry/instrument/detector/counts"
               }
            }
         }
         DATASET "two_theta" {
            DATATYPE  H5T_IEEE_F64LE
            DATASPACE  SIMPLE { ( 31 ) / ( 31 ) }
            DATA {
            (0): 17.9261, 17.9259, 17.9258, 17.9256, 17.9254, 17.9252,
            (6): 17.9251, 17.9249, 17.9247, 17.9246, 17.9244, 17.9243,
            (12): 17.9241, 17.9239, 17.9237, 17.9236, 17.9234, 17.9232,
            (18): 17.9231, 17.9229, 17.9228, 17.9226, 17.9224, 17.9222,
            (24): 17.9221, 17.9219, 17.9217, 17.9216, 17.9214, 17.9213,
            (30): 17.9211
            }
            ATTRIBUTE "units" {
               DATATYPE  H5T_STRING {
                     STRSIZE 7;
                     STRPAD H5T_STR_NULLPAD;
                     CSET H5T_CSET_ASCII;
                     CTYPE H5T_C_S1;
                  }
               DATASPACE  SCALAR
               DATA {
               (0): "degrees"
               }
            }
            ATTRIBUTE "target" {
               DATATYPE  H5T_STRING {
                     STRSIZE 36;
                     STRPAD H5T_STR_NULLPAD;
                     CSET H5T_CSET_ASCII;
                     CTYPE H5T_C_S1;
                  }
               DATASPACE  SCALAR
               DATA {
               (0): "/entry/instrument/detector/two_theta"
               }
            }
         }
      }
      GROUP "instrument" {
         ATTRIBUTE "NX_class" {
            DATATYPE  H5T_STRING {
                  STRSIZE 12;
                  STRPAD H5T_STR_NULLPAD;
                  CSET H5T_CSET_ASCII;
                  CTYPE H5T_C_S1;
               }
            DATASPACE  SCALAR
            DATA {
            (0): "NXinstrument"
            }
         }
         GROUP "detector" {
            ATTRIBUTE "NX_class" {
               DATATYPE  H5T_STRING {
                     STRSIZE 10;
                     STRPAD H5T_STR_NULLPAD;
                     CSET H5T_CSET_ASCII;
                     CTYPE H5T_C_S1;
                  }
               DATASPACE  SCALAR
               DATA {
               (0): "NXdetector"
               }
            }
            DATASET "counts" {
               HARDLINK "/entry/data/counts"
            }
            DATASET "two_theta" {
               HARDLINK "/entry/data/two_theta"
            }
         }
      }
   }
}
}

Look carefully! It appears from the output of h5dump that the actual data for two_theta and counts has moved into the NXdata group at HDF5 path /entry/data! But we stored that data in the NXdetector group at /entry/instrument/detector. This is normal for h5dump output.

A bit of explanation is necessary at this point. The data is not stored in either HDF5 group directly. Instead, HDF5 creates a DATA storage element in the file and posts a reference to that DATA storage element as needed. An HDF5 hard link requests another reference to that same DATA storage element. The h5dump tool describes in full that DATA storage element the first time (alphabetically) it is called. In our case, that is within the NXdata group. The next time it is called, within the NXdetector group, h5dump reports that a hard link has been made and shows the HDF5 path to the description.

NeXus recognizes this behavior of the HDF5 library and adds an additional structure when building hard links, the target attribute, to preserve the original location of the data. Not that it actually matters. The h5toText.py tool knows about the additional NeXus target attribute and shows the data to appear in its original location, in the NXdetector group.

writer_2_1.hdf5:NeXus data file
  entry:NXentry
    @NX_class = NXentry
    data:NXdata
      @NX_class = NXdata
      counts --> /entry/instrument/detector/counts
      two_theta --> /entry/instrument/detector/two_theta
    instrument:NXinstrument
      @NX_class = NXinstrument
      detector:NXdetector
        @NX_class = NXdetector
        counts:NX_INT32[31] = __array
          @units = counts
          @signal = 1
          @axes = two_theta
          @target = /entry/instrument/detector/counts
          __array = [1037, 1318, 1704, '...', 1321]
        two_theta:NX_FLOAT64[31] = __array
          @units = degrees
          @target = /entry/instrument/detector/two_theta
          __array = [17.926079999999999, 17.925909999999998, 17.925750000000001, '...', 17.92108]

Two additional Python modules were used to describe these h5py examples. The source code for each is given here. The first is a library we wrote that helps us create standard NeXus components using h5py. The second is a tool that helps us inspect the content and structure of HDF5 files.

#!/usr/bin/env python
'''
my_lib Library of routines to support NeXus HDF5 files using h5py
'''

import h5py    # HDF5 support
import numpy   # in this case, provides data structures

def makeFile(filename, **attr):
    """
    create and open an empty NeXus HDF5 file using h5py
    
    Any named parameters in the call to this method will be saved as
    attributes of the root of the file.
    Note that **attr is a dictionary of named parameters.

    :param str filename: valid file name
    :param attr: optional keywords of attributes
    :return: h5py file object
    """
    f = h5py.File(filename, "w")
    add_attributes(f, attr)
    return f

def makeGroup(parent, name, nxclass):
    """
    create a NeXus group

    :param obj parent: parent group
    :param str name: valid NeXus group name
    :param str nxclass: valid NeXus class name
    :return: h5py group object
    """
    group = parent.create_group(name)
    group.attrs["NX_class"] = nxclass
    return group

def makeDataset(parent, name, data = None, **attr):
    '''
    create and write data to a dataset in the HDF5 file hierarchy

    :param obj parent: parent group
    :param str name: valid NeXus dataset name
    :param obj data: the data to be saved
    :param attr: optional keywords of attributes
    '''
    if data == None:
        obj = parent.create_dataset(name)
    else:
        obj = parent.create_dataset(name, data=data)
    add_attributes(obj, attr)
    return obj

def makeLink(parent, sourceObject, targetName):
    """
    create a NeXus link in an HDF5 file.

    :param obj parent: parent group of source
    :param obj sourceObject: HDF5 object
    :param str targetName: HDF5 node path string, such as /entry/data/data
    """
    if not 'target' in sourceObject.attrs:
        # NeXus link, NOT an HDF5 link!
        sourceObject.attrs["target"] = str(sourceObject.name)
    parent._id.link(sourceObject.name, targetName, h5py.h5g.LINK_HARD)

def add_attributes(parent, attr):
    """
    add attributes to an h5py data item

    :param obj parent: h5py parent object
    :param dict attr: dictionary of attributes
    """
    if attr and type(attr) == type({}):
        # attr is a dictionary of attributes
        for k, v in attr.items():
            parent.attrs[k] = v

def get_2column_data(fileName):
    '''read two-column data from a file, first column is float, second column is integer'''
    buffer = numpy.loadtxt(fileName).T
    xArr = buffer[0]
    yArr = numpy.asarray(buffer[1],'int32')
    return xArr, yArr

#!/usr/bin/env python

'''
Print the structure of an HDF5 file to stdout

$Id: h5toText.py 1039 2012-02-08 14:28:34Z Pete Jemian $
'''


########### SVN repository information ###################
# $Date: 2012-02-08 14:28:34 +0000 (Wed, 08 Feb 2012) $
# $Author: Pete Jemian $
# $Revision: 1039 $
# $URL: file:///isis/svn/nexus/definitions/trunk/manual/examples/h5py/h5toText.py $
# $Id: h5toText.py 1039 2012-02-08 14:28:34Z Pete Jemian $
########### SVN repository information ###################


import h5py
import os
import sys
import getopt


class H5toText(object):
    '''
    Example usage showing default display::
    
        mc = H5toText(filename)
        mc.array_items_shown = 5
        mc.report()
    '''
    filename = None
    requested_filename = None
    isNeXus = False
    array_items_shown = 5

    def __init__(self, filename, makeReport = False):
        ''' Constructor '''
        self.requested_filename = filename
        if os.path.exists(filename):
            self.filename = filename
            self.isNeXus = self.testIsNeXus()
            if makeReport:
                self.report()

    def report(self):
        ''' reporter '''
        if self.filename == None: return
        f = h5py.File(self.filename, 'r')
        txt = self.filename
        if self.isNeXus:
            txt += ":NeXus data file"
        self.showGroup(f, txt, indentation = "")
        f.close()

    def testIsNeXus(self):
        ''' test if the selected HDF5 file is a NeXus file '''
        result = False
        try:
            f = h5py.File(self.filename, 'r')
            for value in f.itervalues():
                if str(type(value)) in ("<class 'h5py.highlevel.Group'>"):
                    if 'NX_class' in value.attrs:
                        v = value.attrs['NX_class']
                        if type(v) == type("a string"):
                            if v == 'NXentry':
                                result = True
                                break
            f.close()
        except:
            pass
        return result

    def showGroup(self, obj, name, indentation = "  "):
        '''print the contents of the group'''
        nxclass = ""
        if 'NX_class' in obj.attrs:
            class_attr = obj.attrs['NX_class']
            nxclass = ":" + str(class_attr)
        print indentation + name + nxclass
        self.showAttributes(obj, indentation)
        group_equivalents = (
	    "<class 'h5py.highlevel.File'>", 
	    "<class 'h5py.highlevel.Group'>", 
	    "<class 'h5py._hl.group.Group'>",
	)
        # show datasets (and links) first
        for itemname in sorted(obj):
            value = obj[itemname]
            if str(type(value)) not in group_equivalents:
                self.showDataset(value, itemname, indentation = indentation+"  ")
        # then show things that look like groups
        for itemname in sorted(obj):
            value = obj[itemname]
            if str(type(value)) in group_equivalents:
                self.showGroup(value, itemname, indentation = indentation+"  ")

    def showAttributes(self, obj, indentation = "  "):
        '''print any attributes'''
        for name, value in obj.attrs.iteritems():
            print "%s  @%s = %s" % (indentation, name, str(value))

    def showDataset(self, dset, name, indentation = "  "):
        '''print the contents and structure of a dataset'''
        shape = dset.shape
        if self.isNeXus:
            if "target" in dset.attrs:
                if dset.attrs['target'] != dset.name:
                    print "%s%s --> %s" % (indentation, name, dset.attrs['target'])
                    return
        txType = self.getType(dset)
        txShape = self.getShape(dset)
        if shape == (1,):
            value = " = %s" % str(dset[0])
            print "%s%s:%s%s%s" % (indentation, name, txType, txShape, value)
            self.showAttributes(dset, indentation)
        else:
	    print "%s%s:%s%s = __array" % (indentation, name, txType, txShape)
            self.showAttributes(dset, indentation)  # show these before __array
            if self.array_items_shown > 2:
                value = self.formatArray(dset, indentation + '  ')
                print "%s  %s = %s" % (indentation, "__array", value)
            else:
                print "%s  %s: %s" % (indentation, "__array", "not shown")

    def getType(self, obj):
        ''' get the storage (data) type of the dataset '''
        t = str(obj.dtype)
        if t[0:2] == '|S':
            t = 'char[%s]' % t[2:]
        if self.isNeXus:
            t = 'NX_' + t.upper()
        return t

    def getShape(self, obj):
        ''' return the shape of the HDF5 dataset '''
        s = obj.shape
        l = []
        for dim in s:
            l.append(str(dim))
        if l == ['1']:
            result = ""
        else:
            result = "[%s]" % ",".join(l)
        return result

    def formatArray(self, obj, indentation = '  '):
        ''' nicely format an array up to rank=5 '''
        shape = obj.shape
        r = ""
        if len(shape) in (1, 2, 3, 4, 5):
            r = self.formatNdArray(obj, indentation + '  ')
        if len(shape) > 5:
            r = "### no arrays for rank > 5 ###"
        return r

    def decideNumShown(self, n):
        ''' determine how many values to show '''
        if self.array_items_shown != None:
            if n > self.array_items_shown:
                n = self.array_items_shown - 2
        return n

    def formatNdArray(self, obj, indentation = '  '):
        ''' return a list of lower-dimension arrays, nicely formatted '''
        shape = obj.shape
        rank = len(shape)
        if not rank in (1, 2, 3, 4, 5): return None
        n = self.decideNumShown( shape[0] )
        r = []
        for i in range(n):
            if rank == 1: item = obj[i]
            if rank == 2: item = self.formatNdArray(obj[i, :])
            if rank == 3: item = self.formatNdArray(obj[i, :, :], indentation + '  ')
            if rank == 4: item = self.formatNdArray(obj[i, :, :, :], indentation + '  ')
            if rank == 5: item = self.formatNdArray(obj[i, :, :, :, :], indentation + '  ')
            r.append( item )
        if n < shape[0]:
            # skip over most
            r.append("...")
            #  get the last one
            if rank == 1: item = obj[-1]
            if rank == 2: item = self.formatNdArray(obj[-1, :])
            if rank == 3: item = self.formatNdArray(obj[-1, :, :], indentation + '  ')
            if rank == 4: item = self.formatNdArray(obj[-1, :, :, :], indentation + '  ')
            if rank == 5: item = self.formatNdArray(obj[-1, :, :, :, :], indentation + '  ')
            r.append( item )
        if rank == 1:
            s = str( r )
        else:
            s = "[\n" + indentation + '  '
            s += ("\n" + indentation + '  ').join(r)
            s += "\n" + indentation + "]"
        return s


if __name__ == '__main__':
    limit = 5
    filelist = []
    filelist.append('../Create/example1.hdf5')
    filelist.append('../Create/example2.hdf5')
    filelist.append('../Create/example3.hdf5')
    filelist.append('../Create/example4.hdf5')
    filelist.append('../../../NeXus/definitions/trunk/manual/examples/h5py/prj_test.nexus.hdf5')
    filelist.append('../../../NeXus/definitions/exampledata/code/hdf5/dmc01.h5')
    filelist.append('../../../NeXus/definitions/exampledata/code/hdf5/dmc02.h5')
    filelist.append('../../../NeXus/definitions/exampledata/code/hdf5/focus2007n001335.hdf')
    filelist.append('../../../NeXus/definitions/exampledata/code/hdf5/NXtest.h5')
    filelist.append('../../../NeXus/definitions/exampledata/code/hdf5/sans2009n012333.hdf')
    filelist.append('../Create/simple5.nxs')
    filelist.append('../Create/bad.h5')
    #filelist = []
    #filelist.append('testG.h5')
    #filelist.append('testG-pj.h5')
    if len(sys.argv) > 1:
        try:
            opts, args = getopt.getopt(sys.argv[1:], "n:")
        except:
            print
            print "SVN: $Id: h5toText.py 1039 2012-02-08 14:28:34Z Pete Jemian $"
            print "usage: ", sys.argv[0], " [-n ##] HDF5_file_name [another_HDF5_file_name]"
            print "  -n ## : limit number of displayed array items to ## (must be 3 or more or 'None')"
            print
        for item in opts:
            if item[0] == "-n":
                if item[1].lower() == "none":
                    limit = None
                else:
                    limit = int(item[1])
        filelist = args
    for item in filelist:
        mc = H5toText(item)
        mc.array_items_shown = limit
        mc.report()

Here, the output of the command: h5dump -H lrcs3701.nx5 has been edited to only show the first NXdata group (/Histogram1/data):

HDF5 "C:\Users\Pete\Documents\eclipse\NeXus\definitions\exampledata\IPNS\LRMECS\lrcs3701.nx5" {
GROUP "/Histogram1/data" {
   DATASET "data" {
      DATATYPE  H5T_STD_I32LE
      DATASPACE  SIMPLE { ( 148, 750 ) / ( 148, 750 ) }
   }
   DATASET "polar_angle" {
      DATATYPE  H5T_IEEE_F32LE
      DATASPACE  SIMPLE { ( 148 ) / ( 148 ) }
   }
   DATASET "time_of_flight" {
      DATATYPE  H5T_IEEE_F32LE
      DATASPACE  SIMPLE { ( 751 ) / ( 751 ) }
   }
   DATASET "title" {
      DATATYPE  H5T_STRING {
            STRSIZE 44;
            STRPAD H5T_STR_NULLTERM;
            CSET H5T_CSET_ASCII;
            CTYPE H5T_C_S1;
         }
      DATASPACE  SIMPLE { ( 1 ) / ( 1 ) }
   }
}
}

For many, the simplest way to view the data content of an HDF5 file is to use the HDFview^[46] program from The HDF Group. After starting HDFview, the data file may be loaded by dragging it into the main HDF window. On opening up to the first NXdata group /Histogram1/data (as above), and then double-clicking the dataset called: data, we get our first view of the data.

Figure 4.6. LRMECS lrcs3701 data: HDFview

The data may be represented as an image by accessing the Open As menu from HDFview (on Windows, right click the dataset called data and select the Open As item, consult the HDFview documentation for different platform instructions). Be sure to select the Image radio button, and then (accepting everything else as a default) press the Ok button.

Figure 4.7. LRMECS lrcs3701 data: HDFview Open As dialog

Figure 4.8. LRMECS lrcs3701 data: HDFview Image

Another way to visualize this data is to use a commercial package for scientific data visualization and analysis. One such package is IgorPro.^[47] IgorPro provides a browser for HDF5 files that can open our NeXus HDF5 and display the image. Follow the instructions from WaveMetrics to install the HDF5 Browser package:http://www.wavemetrics.com/products/igorpro/dataaccess/hdf5.htm

You may not have to do this step if you have already installed the HDF5 Browser. IgorPro will tell you if it is not installed properly. To install the HDF5 Browser, first start IgorPro. Next, select from the menus and submenus: Data; Load Waves; Packages; Install HDF5 Package as shown in the next figure. IgorPro may direct you to perform more activities before you progress from this step.

Figure 4.9. LRMECS lrcs3701 data: IgorPro install HDF5 Browser

Next, open the HDF5 Browser by selecting from the menus and submenus: Data; Load Waves; New HDF5 Browser as shown in the next figure.

Figure 4.10. LRMECS lrcs3701 data: IgorPro HDFBrowser dialog

Next, click the Open HDF5 File button and open the NeXus HDF5 file lrcs3701.nxs. In the lower left Groups panel, click the data dataset. Also, under the panel on the right called Load Dataset Options, choose No Table as shown. Finally, click the Load Dataset button (in the Datasets group) to display the image.

Figure 4.11. LRMECS lrcs3701 data: IgorPro HDFBrowser dialog

Figure 4.12. LRMECS lrcs3701 data: IgorPro Image