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 content group

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

  • A simple name (no following class) denotes a content 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.

  • Content attributes are noted as @name=”value” pairs. The @ symbol only indicates this is a content attribute and is not part of the attribute name.

  • Content links are shown with a text arrow --> followed by the path of the target (the sequence of names).

Line 1 shows that there is one content 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 content 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: a content 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 content 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 content links, as shown, to content fields in a different content 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

names the NeXus field wavelength of the NeXus group of class NXcrystal …

As it turns out, this syntax is the syntax used in the XML attribute target of an NXDL link. A class path names a NeXus item; it describes every content field or group whose path matches it, whatever the names of the content groups, so it is also used when these names are either unimportant or not specified.

If default names are taken for each class, then the above class path describes this path in the content tree:

/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

A NeXus attribute defined in an NXDL fieldAttributes is named with * in place of the field name:

/NXobject/*@units

It is the NeXus attribute units that any field directly in the class may have, whether or not the class defines that field.