Representation of data examples

Most of the examples of data files have been written in a format intended to show the structure of the file rather than the data content. In some cases, where it is useful, some of the data is shown. Consider this prototype example:

example of NeXus data file structure

 1 entry:NXentry
 2   instrument:NXinstrument
 3     detector:NXdetector
 4       data:[]
 5         @long_name = "strip detector 1-D array"
 6       bins:[0, 1, 2, ... 1023]
 7         @long_name = "bin index numbers"
 8   sample:NXsample
 9     name = "zeolite"
10   data:NXdata
11     @signal = "data"
12     @axes = ["bins", "bins"]
13     @bins_indices = [0, 1]
14     data --> /entry/instrument/detector/data
15     bins --> /entry/instrument/detector/bins

Some words on the notation:

  • Hierarchy is represented by indentation. Objects on the same indentation level are in the same group

  • The combination name:NXclass denotes a NeXus group with name name and class NXclass.

  • A simple name (no following class) denotes a field. An equal sign is used to show the value, where this is important to the example.

  • Sometimes, a data type is specified and possibly a set of dimensions. For example, energy:NX_NUMBER[NE] says energy is a 1-D array of numbers (either integer or floating point) of length NE.

  • Attributes are noted as @name=”value” pairs. The @ symbol only indicates this is an attribute and is not part of the attribute name.

  • Links are shown with a text arrow --> indicating the source of the link (using HDF5 notation listing the sequence of names).

Line 1 shows that there is one group at the root level of the file named entry. This group is of type NXentry which means it conforms to the specification of the NXentry NeXus base class. Using the HDF5 nomenclature, we would refer to this as the /entry group.

Lines 2, 8, and 10: The /entry group contains three subgroups: instrument, sample, and data. These groups are of type NXinstrument, NXsample, and NXdata, respectively.

Line 4: The data of this example is stored in the /entry/instrument/detector group in the dataset called data (HDF5 path is /entry/instrument/detector/data). The indication of data:\[] says that data is an array of unspecified dimension(s).

Line 5: There is one attribute of /entry/instrument/detector/data: long_name. This attribute might be used by a plotting program as the axis title.

Line 6 (reading bins:\[0, 1, 2, ... 1023]) shows that bins is a 1-D array of length presumably 1024. A small, representative selection of values are shown.

Line 7: an attribute that shows a descriptive name of /entry/instrument/detector/bins. This attribute might be used by a NeXus client while plotting the data.

Line 9 (reading name = "zeolite") shows how a string value is represented.

Line 11 says that the default data to be plotted is called data.

Line 12 says that each axis dimension scale of data is described by the field called bins.

Line 13 says that bins will be used for axis 0 and axis 1 of data.

Lines 14-15: The /entry/data) group has two datasets that are actually linked as shown to data sets in a different group. (As you will see later, the NXdata group enables NeXus clients to easily determine what to offer for display on a default plot.)

Class path specification

In some places in this documentation, a path may be shown using the class types rather than names. For example:

/NXentry/NXinstrument/NXcrystal/wavelength

identifies a dataset called wavelength that is inside a group of type NXcrystal …

As it turns out, this syntax is the syntax used in NXDL link specifications. This syntax is also used when the exact name of each group is either unimportant or not specified.

If default names are taken for each class, then the above class path is expressed as this equivalent HDF5 path:

/entry/instrument/crystal/wavelength

In some places in this documentation, where clarity is needed to specify both the path and class name, you may find this equivalent path:

/entry:NXentry/instrument:NXinstrument/crystal:NXcrystal/wavelength