Table of Contents
This chapter actually defines the rules to use for writing valid NeXus files. An explanation of NeXus objects is followed by the definition of NeXus coordinate systems, the rules for structuring files and the rules for storing single items of data.
The structure of NeXus files is extremely flexible, allowing the storage both of simple data sets, such as a single data array and its axes, and also of highly complex data, such as the simulation results or an entire multi-component instrument. This flexibility is a necessity as NeXus strives to capture data from a wild variety of applications in x-ray, muSR and neutron scattering. The flexibility is achieved through a hierarchical structure, with related fields[12] collected together into groups, making NeXus files easy to navigate, even without any documentation. NeXus files are self-describing, and should be easy to understand, at least by those familiar with the experimental technique.
Before discussing the design of NeXus in greater detail it is necessary to define the objects and terms used by NeXus. These are:
- Data Groups
Group data fields and other groups together. Groups represent levels in the NeXus hierarchy
- Data Fields
Multidimensional arrays and scalars representing the actual data to be stored
- Data Attributes
Additional metadata which can be assigned to groups or data fields
- Links
Elements which point to data stored in another place in the file hierarchy
- NeXus Base Classes
Dictionaries of names possible in the various types of NeXus groups
- NeXus Application Definitions
Describe the minimum content of a NeXus file for a particular usage case
In the following sections these elements of NeXus files will be defined in more detail.
NeXus files consist of data groups, which contain fields and/or other groups to form a hierarchical structure. This hierarchy is designed to make it easy to navigate a NeXus file by storing related fields together. Data groups are identified both by a name, which must be unique within a particular group, and a class. There can be multiple groups with the same class but they must have different names (based on the HDF rules). For the class names used with NeXus data groups the prefix NX is reserved. Thus all NeXus class names start with NX.
Data fields contain the essential information stored in a NeXus file. They can be scalar values or multidimensional arrays of a variety of sizes (1-byte, 2-byte, 4-byte, 8-byte) and types (integers, floats, characters). The fields may store both experimental results (counts, detector angles, etc), and other information associated with the experiment (start and end times, user names, etc). Data fields are identified by their names, which must be unique within the group in which they are stored.
Attributes are extra (meta-)information that are associated with particular fields. They are used to annotate the data, e.g. with physical units or calibration offsets, and may be scalar numbers or character strings. In addition, NeXus uses attributes to identify plottable data and their axes, etc. A description of possible attributes can be found in table data attributes. Finally, NeXus files themselves have global attributes which are listed in the global attributes table. that identify the NeXus version, file creation time, etc. Attributes are identified by their names, which must be unique in each field.
Table 2.1. NeXus File Global Attributes
Table 2.2. NeXus Data Attributes. For the full specification of attributes, see the NXDL section in Volume II of the manual.
| Name | Type | Description |
|---|---|---|
| units | NX_CHAR |
Data units, given as character strings, must conform to the NeXus units standard. See the NeXus Data Units section for details. |
| signal | NX_INT | Defines which data set contains the signal
to be plotted
use signal="1" for main signal |
| axes | NX_CHAR |
Defines the names of the dimension scales
for this data set
as a colon-delimited list. Note that some legacy data files
may use a comma as delimiter.
For example, suppose data is an array with
elements data[j][i] (C) or data(i,j)
(Fortran), with dimension scales time_of_flight[i]
and polar_angle[j],
then data would have an
attribute axes="polar_angle:time_of_flight"
in addition to an attribute signal="1".
|
| axis | NX_INT |
The original way of designating data for plotting,
now superceded by
the axes attribute.
This defines
the rank
of the signal data for which this data set is a
dimension scale
in order of the fastest varying index (see a
longer discussion in the section on NXdata structure), i.e. if
the array being stored is data, with elements
data[j][i] in C and data(i,j) in
Fortran, axis would have the following values:
ith dimension (axis="1"),
jth dimension (axis="2"),
etc. |
| primary | NX_INT32 | Defines the order of preference for dimension scales
which apply to the same rank
of signal data. Use primary="1"to indicate preferred
dimension scale |
| long_name | NX_CHAR | Defines title of signal data or axis label of dimension scale |
| calibration_status | NX_CHAR | Defines status of data value - set to "Nominal" or "Measured" |
| offset | NX_INT | Rank values off offsets to use for each dimension if the data is not in C storage order |
| stride | NX_INT | Rank values of steps to use when incrmenting the dimension |
| transformation_type | NX_CHAR | translation or totation |
| vector | NX_FLOAT | 3 values describing the axis of rotation or the direction of translation |
| interpretation | NX_CHAR | Describes how to display the data. Allowed values include:
scaler (0-D data),
spectrum (1-D data),
image (2-D data), or
vertex (3-D data).
|
Links
are pointers to existing data somewhere else.
The concept is very much like
symbolic links in a unix filesystem.
The NeXus definition sometimes requires to
have access to the same data in different groups
in the same file. For example: detector data is stored in the
NXinstrument/NXdetector group
but may be needed in NXdata for automatic plotting.
Rather then replicating the data, NeXus uses
links in such situations. See the figure for
a more descriptive representation of the concept of linking.
Data groups often describe objects in the experiment (monitors, detectors,
monochromators, etc.), so that the contents (both data fields and/or other data
groups) comprise the properties of that object. NeXus has defined a set of standard
objects, or base classes, out of which a NeXus file can be constructed. This is each data group
is identified by a name and a class. The group class, defines the type of object
and the properties that it can contain, whereas the group name defines a unique instance
of that class. These classes are
defined in XML using the NeXus Definition Language (NXDL)
format. All NeXus class types adopted by the NIAC must
begin with NX.
Classes not adopted by the NIAC must not
start with NX.
Note
NeXus base classes are the components used to build the NeXus data structure.
Not all classes define physical objects. Some refer to logical groupings of experimental information, such as plottable data, sample environment logs, beam profiles, etc. There can be multiple instances of each class. On the other hand, a typical NeXus file will only contain a small subset of the possible classes.
NeXus base classes are not proper classes in the same sense as used in object oriented programming languages. In fact the use of the term classes is actually misleading but has established itself during the development of NeXus. NeXus base classes are rather dictionaries of field names and their meanings which are permitted in a particular NeXus group implementing the NeXus class. This sounds complicated but becomes easy if you consider that most NeXus groups describe instrument components. Then for example, a NXmonochromator base class describes all the possible field names which NeXus allows to be used to describe a monochromator.
Most NeXus base classes represent instrument components. Some are used as containers to structure information in a
file (NXentry, NXcollection, NXinstrument, NXprocess, NXparameter).
But there are some base classes which have special uses which need to be mentioned here:
- NXdata
NXdatais used to identify the default plottable data. The notion of a default plot of data is a basic motivation of NeXus.- NXlog
NXlogis used to store time stamped data like the log of a temperature controller. Basically you give a start time, and arrays with a difference in seconds to the start time and the values read.- NXnote
This group provides a place to store general notes, images, video or whatever. A mime type is stored together with a binary blob of data. Please use this only for auxiliary information, for example an image of your sample, or a photo of your boss.
- NXgeometry
NXgeometryand its subgroupsNXtranslation,NXorientation,NXshapeare used to store absolute positions in the laboratory coordinate system or to define shapes.
These groups can appear anywhere in the NeXus hierarchy, where needed. Preferably close to the component they
annotate or in a NXcollection. All of the base classes are documented in the reference manual.
The most notable special base class (or group in NeXus is NXdata.
NXdata is the answer to a basic motivation of NeXus to facilitate automatic
plotting of data.
NXdata is designed to contain the main dataset and its associated dimension scales (axes)
of a NeXus data file. The
usage scenario is that an automatic data plotting program just opens a NXentry and then continues to search for any NXdata
groups. These NXdata groups represent the plottable data. Here is the way an automatic plotting program ought to work:
Search for
NXentrygroups-
Open an
NXentry Search for
NXdatagroupsOpen an
NXdatagroup-
Identify the plottable data.
Search for a dataset with attribute
signal=1. This is your main dataset. (There should be only one dataset that matches.)-
Try to read the
axesattribute of the main dataset, if it exists. -
If
axesdoes not exist:Search for datasets with attributes
axis=1,axis=2, etc. These are the datasets describing your axis. There may be several datasets for any axis, i.e. there may be multiple datasets with the attributeaxis=1. Among them the dataset with the attributeprimary=1is the preferred one. All others are alternative dimension scales.
Having found the default plottable data and its dimension scales: make the plot
The objects described so far provide us with the means to store data from a wide variety of instruments, simulations or processed data as resulting from data analysis. But NeXus strives to express strict standards for certain applications of NeXus too. The tool which NeXus uses for the expression of such strict standards is the NeXus Application Definition. A NeXus Application Definition describes which groups and data items have to be present in a file in order to properly describe an application of NeXus. For example for describing a powder diffraction experiment. Typically an application definition will contain only a small subset of the many groups and fields defined in NeXus. NeXus application definitions are also expressed in the NeXus Definition Language (NXDL). A tool exists which allows one to validate a NeXus file against a given application definition.
Note
NeXus application definitions define the minimum information necessary to satisfy data analysis or other data processing.
Another way to look at a NeXus application definition is as a contract between a file producer (writer) and a file consumer (reader). The contract reads: If you write your files following a particular NeXus application definition, I can process these files with my software.
Yet another way to look at a NeXus application definition is to understand it as an interface definition between data files and the software which uses this file. Much like an interface in the Java or other modern object oriented programming languages.
In contrast to NeXus base classes, NeXus supports inheritance in application definitions.
Please note that a NeXus Application Definition will only define the bare minimum of data necessary to perform common analysis with data. Practical files will nearly always contain more data. One of the beauties of NeXus is that it is alwasy possible to add more data to a file without breaking its compliance with its application definition.
[12] In this manual, we use the terms field, data field, and data item synonymously to be consistent with their meaning between NeXus data file instances and NXDL specification files.