Write a NeXus HDF5 file with plottable data¶

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 content group. One appropriate NeXus class is NXdetector. This group is placed in a NXinstrument group which is placed in a NXentry group. To support a default plot, we provide a NXdata group. Rather than duplicate the same data already placed in the detector group, we choose to make content links to those datasets in the NXdata group. (Compare the next figure with Content links in a NeXus file in the NeXus Design chapter of the NeXus User Manual.) The NeXus Design chapter provides a figure (Content links in a NeXus file) with a small variation from our previous example, placing the measured data within the /entry/instrument/detector group. Content links to that data are made in the /entry/data group.

fig.simple_example_write2 — h5py example showing content links 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 nexusformat with content links
according to the example from Figure 2.1 in the Design chapter
"""

from pathlib import Path

import numpy
from nexusformat.nexus import NXdata
from nexusformat.nexus import NXdetector
from nexusformat.nexus import NXentry
from nexusformat.nexus import NXfield
from nexusformat.nexus import NXinstrument
from nexusformat.nexus import NXlink
from nexusformat.nexus import nxopen

filename = str(Path(__file__).absolute().parent.parent / "simple_example.dat")
buffer = numpy.loadtxt(filename).T
tthData = buffer[0]  # float[]
countsData = numpy.asarray(buffer[1], "int32")  # int[]

with nxopen("simple_example_write2.hdf5", "w") as f:  # create the HDF5 NeXus file
    f["entry"] = NXentry()
    f["entry/instrument"] = NXinstrument()
    f["entry/instrument/detector"] = NXdetector()

    # store the data in the NXdetector group
    f["entry/instrument/detector/two_theta"] = NXfield(tthData, units="degrees")
    f["entry/instrument/detector/counts"] = NXfield(countsData, units="counts")

    f["entry/data"] = NXdata(
        NXlink("/entry/instrument/detector/counts"),
        NXlink("/entry/instrument/detector/two_theta"),
    )
    f["entry/data"].set_default()

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

from pathlib import Path

import h5py
import numpy

filename = str(Path(__file__).absolute().parent.parent / "simple_example.dat")
buffer = numpy.loadtxt(filename).T
tthData = buffer[0]  # float[]
countsData = numpy.asarray(buffer[1], "int32")  # int[]

with h5py.File("simple_example_write2.hdf5", "w") as f:  # create the HDF5 NeXus file
    f.attrs["default"] = "entry"

    nxentry = f.create_group("entry")
    nxentry.attrs["NX_class"] = "NXentry"
    nxentry.attrs["default"] = "data"

    nxinstrument = nxentry.create_group("instrument")
    nxinstrument.attrs["NX_class"] = "NXinstrument"

    nxdetector = nxinstrument.create_group("detector")
    nxdetector.attrs["NX_class"] = "NXdetector"

    # store the data in the NXdetector group
    ds_tth = nxdetector.create_dataset("two_theta", data=tthData)
    ds_tth.attrs["units"] = "degrees"
    ds_counts = nxdetector.create_dataset("counts", data=countsData)
    ds_counts.attrs["units"] = "counts"

    # create the NXdata group to define the default plot
    nxdata = nxentry.create_group("data")
    nxdata.attrs["NX_class"] = "NXdata"
    nxdata.attrs["signal"] = "counts"
    nxdata.attrs["axes"] = "two_theta"
    nxdata.attrs["two_theta_indices"] = [
        0,
    ]

    source_addr = "/entry/instrument/detector/two_theta"  # existing data
    target_addr = "two_theta"  # new location
    ds_tth.attrs["target"] = source_addr  # path of the target
    nxdata[target_addr] = f[source_addr]  # HDF5 hard link

    source_addr = "/entry/instrument/detector/counts"  # existing data
    target_addr = "counts"  # new location
    ds_counts.attrs["target"] = source_addr  # path of the target
    nxdata[target_addr] = f[source_addr]  # HDF5 hard link

It is interesting to compare the output of the h5dump of the data file simple_example_write2.hdf5 with our Python instructions. See the downloads section below.

Look carefully! It appears in 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 an HDF5 hard link has been made and shows the HDF5 path to the description.

HDF5 makes no distinction between the two paths of a hard-linked object. NeXus does: the target content attribute holds the path of the target, so NXdata/two_theta is a content link to its target in the NXdetector group. The punx tree tool knows about the target attribute and shows the data at its target, in the NXdetector group.

  @default = "entry"
  entry:NXentry
    @NX_class = "NXentry"
    @default = "data"
    data:NXdata
      @NX_class = "NXdata"
      @axes = "two_theta"
      @signal = "counts"
      @two_theta_indices = [0]
      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] = [1037, 1318, 1704, '...', 1321]
          @target = "/entry/instrument/detector/counts"
          @units = "counts"
        two_theta:NX_FLOAT64[31] = [17.92608, 17.92591, 17.92575, '...', 17.92108]
          @target = "/entry/instrument/detector/two_theta"
          @units = "degrees"

downloads¶

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

file	description
`../simple_example.dat`	2-column ASCII data used in this section
`simple_example_write2.py`	h5py code to write example simple_example_write2
`nexusformat/simple_example_write2.py`	nexusformat code to write example simple_example_write2
`simple_example_write2.hdf5`	NeXus file written by this code
`simple_example_write2_h5dump.txt`	h5dump analysis of the NeXus file
`simple_example_write2_structure.txt`	punx tree analysis of the NeXus file

Write a NeXus HDF5 file with plottable data¶

downloads¶

Table of Contents

Previous topic

Next topic

This Page

Google search