1.2.3.2. Rules for Storing Data Items in NeXus Files

This section describes the rules which apply for storing single data items.

Naming Conventions

Names of content groups and fields, and the XML attribute name of NXDL groups and fields, follow a naming convention described by the following rules:

• The names of content groups and fields must only contain a restricted set of characters.

  This set is described by a regular expression syntax regular expression regular expression syntax, as described below.

• For the class names [1] of content groups, the prefix NX is reserved as shown in the table below. Thus all NeXus class names start with NX. The chapter titled NeXus: Reference Documentation lists the available NeXus class names as either base classes, application definitions, or contributed definitions.

[1]

The class name is the value of the content attribute NX_class of a content group (in HDF5, an HDF5 attribute of the HDF5 group). This class name is different than the name of the content group. This is important when not using the NAPI to either read or write the HDF5 data file.

Names of content groups and fields

The names of content groups and fields are validated according to these boundaries:

• Recommended names [3]

  • lower case words separated by underscores and, if needed, with a trailing number

  • NOTE: this is used by the NeXus base classes

• Allowed names

  • any combination of upper and lower case letter, numbers, underscores and periods, except that periods cannot be at the start or end of the string

  • NOTE: this matches the validItemName regular expression below

• Invalid names

  • NOTE: does not match the validItemName regular expression below

Regular expression pattern for names of content groups and fields

The NIAC recognises that the majority of the world uses characters outside of the basic latin (a.k.a. US-ASCII, 7-bit ASCII) [2] set currently included in the allowed names. The restriction given here reflects current technical issues and we expect to revisit the issue and relax such restrictions in future.

[2]

https://en.wikipedia.org/wiki/ASCII

The names of NeXus group and field items must match this regular expression (named validItemName in the XML Schema file: nxdl.xsd):

^[a-zA-Z0-9_]([a-zA-Z0-9_.]*[a-zA-Z0-9_])?$

The length should be limited to no more than 63 characters (historically imposed by the HDF4 rules for names).

It is recognized that some facilities will construct data files with content group and field names with upper case letters or start names with a number or include a period in a name. [3]

[3] (1,2)

NeXus data files with content group or field names that match the regular expression but contain upper case characters, start with a digit, or include a period in the group or field names might not be accepted by all software that reads NeXus data files. These names will be flagged as a warning during data file validation.

Use of underscore in descriptive names

Sometimes it is necessary to combine words in order to build a descriptive name for a NeXus field or group. In such cases lowercase words are connected by underscores.

number_of_lenses

For all fields, only the names of NeXus fields that the base classes define should be used. If a NeXus field name or even a complete component is missing, please suggest the addition to the NIAC: The NeXus International Advisory Committee. The addition will usually be accepted provided it is not a duplication of an existing NeXus field and adequately documented.

Note

The NeXus base classes provide a comprehensive dictionary of terms that can be used for each class. The expected spelling and definition of each term is specified in the base classes. It is not required to provide all the terms specified in a base class. Terms with other names are permitted but might not be recognized by standard software. Rather than persist in using names not specified in the standard, please suggest additions to the NIAC: The NeXus International Advisory Committee.

The values of a NeXus field are readback values. This means values as read from the detector, other hardware, etc. There are occasions where it is sensible to store the target value the variable was supposed to have. In such cases, the target value is stored with a name built by appending _set to the NeXus (readback) field name.

Consider this example:

temperature
temperature_set

The content field temperature will hold the readback from the cryostat/furnace/whatever. The content field temperature_set will hold the target value for the temperature as set by the experiment control software.

Some NeXus fields share a common part of their name and an additional part name that makes the whole name specific. For example, a unit_cell might have parts named abc, alphabetagamma, and volume. It is recommended to write them with the common part first, an underscore (_), and then the specific part. In this way, the fields will sort alphabetically on the common name. So, in this example:

unit_cell_abc
unit_cell_alphabetagamma
unit_cell_volume

Reserved prefixes

When naming a content attribute, field, or group, NeXus has reserved certain prefixes to the names to ensure that names written in NeXus files will not conflict with future releases as the NeXus standard evolves. Prefixes should follow a naming scheme of uppercase letters followed by an underscore, but exceptions will be made for cases already in wide use. The following table lists the prefixes reserved by NeXus.

prefix	use	meaning	URL
BLUESKY_	attributes	reserved for use by Bluesky project	https://blueskyproject.io
DECTRIS_	attributes, fields	reserved for use by Dectris	https://www.dectris.com
IDF_	attributes	reserved for use by pulsedTD Muon definition	https://www.isis.stfc.ac.uk/Pages/nexus-definition-v27924.pdf
NDAttr	attributes	reserved for use by EPICS area detector	https://github.com/areaDetector
NX	NXDL class	for the class names used with NeXus groups	https://www.nexusformat.org
NX_	attributes	reserved for use by NeXus	https://www.nexusformat.org
PDBX_	attributes	reserved for the US protein data bank	https://www.rcsb.org
SAS_	attributes	reserved for use by canSAS	https://www.cansas.org
SILX_	attributes	reserved for use by silx	https://www.silx.org
identifier	fields	reserved for unique identfier in groups

Reserved suffixes

When naming a NeXus field, NeXus has reserved certain suffixes to the names so that a specific meaning may be attached. Consider a NeXus field named DATASET, the following table lists the suffixes reserved by NeXus.

suffix	reference	meaning
_end	NXtransformations	end points of the motions that start with DATASET
_errors	NXdata	uncertainties (a.k.a., errors)
_increment_set	NXtransformations	intended average range through which the corresponding axis moves during the exposure of a frame
_indices	NXdata	Integer array that defines the indices of the NeXus signal field which need to be used in the DATASET in order to reference the corresponding axis value
_mask		NeXus field containing a signal mask, where 0 means the pixel is not masked. If required, bit masks are defined in NXdetector pixel_mask.
_set	target values	Target value of DATASET
_weights		divide DATASET by these weights [4]
_scaling_factor	NXdata	Multiply DATASET by this factor [4]
_offset	NXdata	Add this factor to DATASET [4]

[4] (1,2,3)

If DATASET_weights exists and has the same shape as DATASET, you are supposed to divide DATASET by the weights. Similarly, if DATASET_scaling_factor and/or DATASET_offset exist, apply this equation: (DATASET + DATASET_offset) * DATASET_scaling_factor

Variants

Sometimes it is necessary to store alternate values of a field in a NeXus file. A common example may be the beam center of which a rough value is available at data acquisition. But later on, a better beam center is calculated as part of the data reduction. In order to store this without losing the historical information, the field with the best value can have the NeXus attribute @variant (defined in NXobject), which names a new field that holds the obsolete value. If even better values become available, further fields can be inserted into the chain of variant attributes pointing to the preceeding value for the field. A reader can thus keep the best value in the pre-defined field, and also be able to follow the variant chain and locate older variants.

A little example is in order to illustrate the scheme:

beam_center_x
        @variant=beam_center_x_refined
beam_center_x_refined
        @variant=beam_center_x_initial_guess
beam_center_x_initial_guess

NeXus borrowed this scheme from CIF. In this way all the different variants of a content field can be preserved. The expectation is that variants will be rarely used and NXprocess groups with the results of data reduction will be written instead.

Uncertainties or Errors

It is desirable to store experimental errors (also known as uncertainties) together with the data. NeXus supports this through a convention: NXobject defines the NeXus field FIELDNAME_errors for the uncertainties or experimental errors of the NeXus field FIELDNAME. It has the same shape as FIELDNAME.

An example, from NXdetector:

data
data_errors
beam_center_x
beam_center_x_errors

Where data errors would contain the errors on data, and beam_center_x_errors the error on the beam center for x.

NeXus Array Storage Order

NeXus stores multi-dimensional arrays of physical values in C language storage order, where the first dimension has the slowest varying index when iterating through the array in storage order, and the last dimension is the fastest varying. This is the rule. Good reasons are required to deviate from this rule.

Where the array contains data from a detector, the array dimensions may correspond to physical directions or axes. The slowest, slow, fast, fastest qualifiers can then apply to these axes too.

It is possible to store data in storage orders other than C language order.

As well it is possible to specify that the data needs to be converted first before being useful. Consider one situation, when data must be streamed to disk as fast as possible and conversion to C language storage order causes unnecessary latency. This case presents a good reason to make an exception to the standard rule.

Non C Storage Order

In order to indicate that the storage order is different from C storage order, a field has the two NeXus attributes @data_offset and @stride that NXobject defines, which together define the storage layout of the data. They contain rank numbers according to the rank of the multidimensional field. data_offset gives the position of the first stored value in each dimension. stride gives the step to make when incrementing the dimension. This is best explained by some examples.

Offset and Stride for 1 D data:

   * raw data = 0 1 2 3 4 5 6 7 8 9
      size[1] = { 10 }  // assume uniform overall array dimensions

   * default stride:
      stride[1] = { 1 }
      offset[1] = { 0 }
      for i:
         result[i]:
            0 1 2 3 4 5 6 7 8 9

   * reverse stride:
      stride[1] = { -1 }
      offset[1] = { 9 }
      for i:
         result[i]:
            9 8 7 6 5 4 3 2 1 0

Offset and Stride for 2D Data

   * raw data = 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
      size[2] = { 4, 5 }  // assume uniform overall array dimensions

   * row major (C) stride:
      stride[2] = { 5, 1 }
      offset[2] = { 0, 0 }
      for i:
         for j:
            result[i][j]:
               0 1 2 3 4
               5 6 7 8 9
               10 11 12 13 14
               15 16 17 18 19

   * column major (Fortran) stride:
      stride[2] = { 1, 4 }
      offset[2] = { 0, 0 }
      for i:
         for j:
            result[i][j]:
               0 4 8 12 16
               1 5 9 13 17
               2 6 10 14 18
               3 7 11 15 19

   * "crazy reverse" row major (C) stride:
      stride[2] = { -5, -1 }
      offset[2] = { 4, 5 }
      for i:
         for j:
            result[i][j]:
               19 18 17 16 15
               14 13 12 11 10
               9 8 7 6 5
               4 3 2 1 0   

Offset and Stride for 3D Data

  * raw data = 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
         20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
         40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
      size[3] = { 3, 4, 5 }  // assume uniform overall array dimensions

   * row major (C) stride:
      stride[3] = { 20, 5, 1 }
      offset[3] = { 0, 0, 0 }
      for i:
         for j:
            for k:
               result[i][j][k]:
                  0 1 2 3 4
                  5 6 7 8 9
                  10 11 12 13 14
                  15 16 17 18 19

                  20 21 22 23 24
                  25 26 27 28 29
                  30 31 32 33 34
                  35 36 37 38 39

                  40 41 42 43 44
                  45 46 47 48 49
                  50 51 52 53 54
                  55 56 57 58 59

   * column major (Fortran) stride:
      stride[3] = { 1, 3, 12 }
      offset[3] = { 0, 0, 0 }
      for i:
         for j:
            for k:
               result[i][j][k]:
                  0 12 24 36 48
                  3 15 27 39 51
                  6 18 30 42 54
                  9 21 33 45 57

                  1 13 25 37 49
                  4 16 28 40 52
                  7 19 31 43 55
                  10 22 34 46 58

                  2 14 26 38 50
                  5 17 29 41 53
                  8 20 32 44 56
                  11 23 35 47 59

NeXus Data Types

description	matching regular expression
integer	NX_INT(8|16|32|64)
floating-point	NX_FLOAT(32|64)
array	(\\[0-9\\])?
valid item name	^[a-zA-Z0-9_]([a-zA-Z0-9_.]*[a-zA-Z0-9_])?$
valid class name	^NX[A-Za-z0-9_]*$

NeXus supports numeric data as either integer or floating-point numbers. A number follows that indicates the number of bits in the word. The table above shows the regular expressions that match the data type specifier.

integers

NX_INT8, NX_INT16, NX_INT32, or NX_INT64

floating-point numbers

NX_FLOAT32 or NX_FLOAT64

date / time stamps

NX_DATE_TIME or ISO8601: Dates and times are specified using ISO-8601 standard definitions. Refer to NeXus dates and times.

strings

NX_CHAR: The preferred string representation is UTF-8. Both fixed-length strings and variable-length strings are valid. String arrays cannot be used where only a string is expected (title, start_time, end_time, the NeXus attribute NX_class, …). NeXus fields or attributes requiring the use of string arrays will be clearly marked as such (like the NeXus attribute auxiliary_signals of NXdata).

binary data

Binary data is to be written as UINT8.

images

Binary image data is to be written using UINT8, the same as binary data, but with an accompanying image mime-type. If the data is text, the line terminator is [CR][LF].

NeXus dates and times

NeXus dates and times should be stored using the ISO 8601 [5] format, e.g. 1996-07-31T21:15:22+0600 (which includes a time zone offset of +0600). Note: The time zone offset is always numeric or Z (which means UTC). The standard also allows for time intervals in fractional seconds with 1 or more digits of precision. This avoids confusion, e.g. between U.S. and European conventions, and is appropriate for machine sorting. It is recommended to add an explicit time zone, otherwise the local time zone is assumed per ISO8601. The norm is that if there is no time zone, it is assumed local time, however, when a file moves from one country to another it is undefined. If the local time zone is written, the ambiguity is gone.

[5]

ISO 8601: https://www.w3.org/TR/NOTE-datetime

strftime() format specifiers for ISO-8601 time

%Y-%m-%dT%H:%M:%S%z

Note

Note that the T appears literally in the string, to indicate the beginning of the time element, as specified in ISO 8601. It is common to use a space in place of the T, such as 1996-07-31 21:15:22+0600. While human-readable (and later allowed in a relaxed revision of the standard), compatibility with libraries supporting the ISO 8601 standard is not assured with this substitution. The strftime() format specifier for this is “%Y-%m-%d %H:%M:%S%z”.

NeXus Data Units

Given the plethora of possible applications of NeXus, it is difficult to define units to use. Therefore, the general rule is that you are free to store data in any unit you find fit. However, a content field described by a NeXus field with a units category (such as units="NX_LENGTH") must have the content attribute @units, with units of that category. Wherever possible, SI units are preferred. Units are given in the NeXus attribute units, of data type NX_CHAR, and describe the engineering units. The string should be appropriate for the value. Values for the NeXus units must be specified in a format compatible with Unidata UDunits [6] Application definitions may specify units to be used for NeXus fields using an enumeration.

[6]

The UDunits specification also includes instructions for derived units. At present, the contents of NeXus units attributes are not validated in data files.

Storing Detectors

There are very different types of detectors out there. Storing their data can be a challenge. As a general guide line: if the detector has some well defined form, this should be reflected in the data file. A linear detector becomes a linear array, a rectangular detector becomes an array of size xsize times ysize. Some detectors are so irregular that this does not work. Then the detector data is stored as a linear array, with the index being detector number till ndet. Such detectors must be accompanied by further arrays of length ndet which give azimuthal_angle, polar_angle and distance for each detector.

If data from a time of flight (TOF) instrument must be described, then the TOF dimension becomes the last dimension, for example an area detector of xsize vs. ysize is stored with TOF as an array with dimensions xsize, ysize, ntof.

Monitors are Special

Monitors, detectors that measure the properties of the experimental probe rather than the probe’s interaction with the sample, have a special place in NeXus files. Monitors are crucial to normalize data. To emphasize their role, monitors are not stored in the NXinstrument hierarchy but on NXentry level in their own content groups as there might be multiple monitors. Of special importance is the monitor in a content group called control. This is the main monitor against which the data has to be normalized. This group also contains the counting control information, i.e. counting mode, times, etc.

Monitor data may be multidimensional. Good examples are scan monitors where a monitor value per scan point is expected or time-of-flight monitors.

Find the plottable data

Simple plotting is one of the motivations for the NeXus standard. To implement simple plotting, a mechanism must exist to identify the default data for visualization (plotting) in any NeXus data file. Over its history the NIAC has agreed upon a method of applying metadata to identify the default plottable data. This metadata has always been specified as HDF attributes. With the evolution of the underlying file formats and the NeXus data standard, the method to identify the default plottable data has evolved, undergoing three distinct versions.

version 1:

Associating plottable data by dimension number using the axis content attribute

version 2:

Associating plottable data by name using the axes content attribute

version 3:

Associating plottable data using content attributes applied to the NXdata group

Consult the NeXus API section, which describes the routines available to program these operations. In the course of time, generic NeXus browsers will provide this functionality automatically.

For programmers who may encounter NeXus data files written using any of these methods, we present the algorithm for each method to find the default plottable data. It is recommended to start with the most recent method, Version 3, first.

Version 3

The third (current) method to identify the default plottable data is as follows:

1. Start at the top level of the NeXus data file (the root of the HDF5 hierarchy).

2. Pick the default NXentry group.

   If the root has a content attribute default, the attribute’s value is the name of the NXentry group to be used. (The value of the default attribute names an existing child of this group. The child must itself be a content group, not a content field.) If no default attribute exists, pick any NXentry group. This is trivial if there is only one NXentry group.

   

   Find plottable data: select the NXentry group

3. Pick the default NXdata group.

   Open the NXentry group selected above. If it has a content attribute default, the attribute’s value is the name of the NXdata group to be used. (The value of the default attribute names an existing child of this group. The child must itself be a content group, not a content field.) If no default attribute exists, pick any NXdata group. This is trivial if there is only one NXdata group.

   

   Find plottable data: select the NXdata group

1. Pick the default plottable content field (the signal data).

   Open the NXdata group selected above. If it has a content attribute signal, the attribute’s value is the name of the field to be plotted. (The value of the signal attribute names an existing child of this group. The child must itself be a content field.) If no signal attribute is present on the NXdata group, then proceed to try an older NeXus method to find the default plottable data.

   

   Find plottable data: select the signal data

   1. Pick the content fields with the dimension scales (the axes).

      If the same NXdata group has a content attribute axes, then its value is a string (signal data is 1-D) or string array (signal data is 2-D or higher rank) naming the field in this group to be used as dimension scales of the default plottable data. The number of values given must be equal to the rank of the signal data. These are the abscissae of the plottable signal data.

      If no field is available to provide a dimension scale for a given dimension, then a “.” will be used in that position. In such cases, programmers are expected to use an integer sequence starting from 0 for each position along that dimension.

   2. Associate the dimension scales with each dimension of the plottable data.

      For each content field (its name is AXISNAME) in axes that provides a dimension scale, there will be a content attribute AXISNAME_indices of the NXdata group, which value is an .. integer or integer array with value of the dimensions of the signal data to which this dimension scale applies.

      If no AXISNAME_indices attribute is provided, a programmer is encouraged to make best efforts assuming the intent of this NXdata group to provide a default plot. The AXISNAME_indices attribute is only required when necessary to resolve ambiguity.

      It is possible there may be more than one AXISNAME_indices attribute with the same value or values. This indicates the possibilty of using alternate abscissae along this (these) dimension(s). The field named in the axes attribute indicates the intention of the data file writer as to which field should be used by default.

2. Plot the signal data, given axes and AXISNAME_indices.

When all the default and signal content attributes are present, this Python code example will identify directly the default plottable data (assuming a plot() function has been defined by some code:

group = h5py.File(hdf5_file_name, "r")

while "default" in group.attrs:
    child_group_name = group.attrs["default"]
    group = group[child_group_name]

# assumes group.attrs["NX_class"] == "NXdata"
signal_field_name = group.attrs["signal"]
data = group[signal_field_name]

plot(data)

Version 2

Tip

Try this method for older NeXus data files and Version 3 fails..

The second method to identify the default plottable data is as follows:

1. Start at the top level of the NeXus data file.

2. Loop through the content groups with class NXentry until the next step succeeds.

   

   Find plottable data: pick a NXentry group

3. Open the NXentry group and loop through the subgroups with class NXdata until the next step succeeds.

   

   Find plottable data: pick a NXdata group

4. Open the NXdata group and loop through the content fields for the one field with the content attribute signal="1". Note: There should be only one field that matches.

   This is the default plottable data.

   If there is no such signal="1" field, proceed to try an older NeXus method to find the default plottable data.

   1. If this field has a content attribute axes:

      1. The axes attribute value contains a colon (or comma) delimited list (in the C-order of the data array) with the names of the dimension scales associated with the plottable data. Such as: axes="polar_angle:time_of_flight"

      2. Parse axes and open the content fields to describe your dimension scales

   2. If this field has no attribute axes:

      1. Search for content fields with @axis set to 1, 2, etc.

      2. These are the fields describing your axis. There may be several fields for any axis, i.e. there may be multiple fields with the attribute axis=1. Among them the field with the attribute primary=1 is the preferred one. All others are alternative dimension scales.

5. Having found the default plottable data and its dimension scales: make the plot.

   

   Find plottable data: select the signal data

Version 1

Tip

Try this method for older NeXus data files.

The first method to identify the default plottable data is as follows:

1. Open the first top level content group with class NXentry.

   

   Find plottable data: pick the first NXentry group

2. Open the first content group with class NXdata.

   

   Find plottable data: pick the first NXdata group

3. Loop through content fields in this group searching for the one with the content attribute signal="1" indicating this field has the plottable data.

4. Search for the one-dimensional content fields with the content attribute primary=1. These are the dimension scales to label the axes of each dimension of the data.

5. Link each dimension scale to the respective data dimension by the content attribute axis (axis=1, axis=2, … up to the rank of the data).

   

   Find plottable data: select the signal data

6. If necessary, close this NXdata group, search the next NXdata group, repeating steps 3 to 5.

7. If necessary, close the NXentry group, search the next NXentry group, repeating steps 2 to 6.

Associating Multi Dimensional Data with Axis Data

NeXus allows for storage of multi dimensional arrays of data. It is this data that presents the most challenge for description. In most cases it is not sufficient to just have the indices into the array as a label for the dimensions of the data. Usually the information which physical value corresponds to an index into a dimension of the multi dimensional data set. To this purpose a means is needed to locate appropriate data arrays which describe what each dimension of a multi dimensional data set actually corresponds too. There is a standard HDF facility to do this: it is called dimension scales. Unfortunately, when NeXus was first designed, there was only one global namespace for dimension scales. Thus NeXus had to devise its own scheme for locating axis data which is described here. A side effect of the NeXus scheme is that it is possible to have multiple mappings of a given dimension to physical data. For example, a TOF data set can have the TOF dimension as raw TOF or as energy.

There are now three methods of associating each data dimension to its respective dimension scale. Only the first method is recommended now, the other two (older methods) are now discouraged.

1. Associating plottable data using content attributes applied to the NXdata group

2. Associating plottable data by name using the axes content attribute

3. Associating plottable data by dimension number using the axis content attribute

The recommended method uses the content attribute axes applied to the NXdata group to specify the names of each dimension scale. A prerequisite is that the NeXus fields of the axes are in the same NXdata group as the plottable data. If this leads to data duplication, use content links.

---

Associating plottable data using content attributes applied to the NXdata group

Tip

Recommended: This is the “NIAC2014” method recommended for all new NeXus data files.

The default data to be plotted (and any associated axes) is specified using content attributes attached to the NXdata group.

signal:

Defines the name of the default content field in the NXdata group. A content field of this name must exist (it may be a content link).

It is recommended to use this attribute rather than adding a signal attribute to the field. [7] The procedure to identify the default data to be plotted is quite simple. Given any NeXus data file, any NXentry, or any NXdata, follow the chain as it is described from that point. Specifically:

• The root of the NeXus file may have a default content attribute that names the default NXentry group. This attribute may be omitted if there is only one NXentry group. If a second NXentry group is later added, the default attribute must be added then.

• Every NXentry group may have a default attribute that names the default NXdata group. This attribute may be omitted if there is only one NXdata group or if no NXdata is present. If a second NXdata group is later added, the default attribute must be added then.

• Every NXdata group will have a signal attribute that names the field name to be plotted by default. This attribute is required.

axes:

String array [8] that defines the independent content fields used in the default plot for all of the dimensions of the signal field. One entry is provided for every dimension in the signal field.

The field(s) named as values (known as “axes”) of this attribute must exist. An axis slice is specified using the NeXus attribute AXISNAME_indices of NXdata as described below (where the text shown here as AXISNAME is to be replaced by the actual field name).

When no default axis is available for a particular dimension of the plottable data, use a “.” in that position.

See examples provided on the NeXus webpage ([9]).

If there are no axes at all (such as with a stack of images), the axes attribute can be omitted.

AXISNAME_indices:

The NeXus attribute AXISNAME_indices indicates the dependency relationship of the NeXus field AXISNAME (a field of this NXdata group) with one or more dimensions of the plottable data.

Integer array [8] that defines the indices of the signal field (that field will be a multidimensional array) which need to be used in the AXISNAME field in order to reference the corresponding axis value.

The first index of an array is 0 (zero).

Here, AXISNAME is to be replaced by the name of each field described in the axes attribute. An example with 2-D data, \(d(t,P)\), will illustrate:

data_2d:NXdata
    @signal="data"
    @axes=["time","pressure"]
    @time_indices=0
    @pressure_indices=1
    data: float[1000,20]
    time: float[1000]
    pressure: float[20]

This attribute is to be provided in all situations. However, if the indices attributes are missing (such as for data files written before this specification), file readers are encouraged to make their best efforts to plot the data. Thus the implementation of the AXISNAME_indices attribute is based on the model of “strict writer, liberal reader”.

[7]

Summary of the discussion at NIAC2014 to revise how to find default data: https://www.nexusformat.org/2014_How_to_find_default_data.html

[8] (1,2)

Note on array-valued content attributes: Attributes potentially containing multiple values (axes and _indices) are to be written as string or integer arrays, to avoid string parsing in reading applications.

[9] (1,2)

NIAC2014 proposition: https://www.nexusformat.org/2014_axes_and_uncertainties.html

Examples

Several examples are provided to illustrate this method. More examples are available in the NeXus webpage ([9]).

simple 1-D data example showing how to identify the default data (counts vs. mr)

In the first example, storage of a 1-D data set (counts vs. mr) is described.

datafile.hdf5:NeXus data file
  @default="entry"
  entry:NXentry
    @default="data"
    data:NXdata
      @signal="counts"
      @axes="mr"
      @mr_indices=0
      counts: float[100]  --> the default dependent data
      mr: float[100]      --> the default independent data

2-D data example showing how to identify the default data and associated dimension scales

A 2-D data set, data as a function of time and pressure is described. By default as indicated by the axes content attribute, pressure is to be used. The temperature array is described as a substitute for pressure (so it replaces dimension 1 of data as indicated by the temperature_indices attribute).

datafile.hdf5:NeXus data file
  @default="entry"
  entry:NXentry
    @default="data_2d"
    data_2d:NXdata
      @signal="data"
      @axes=["time","pressure"]
      @pressure_indices=1
      @temperature_indices=1
      @time_indices=0
      data: float[1000,20]
      pressure: float[20]
      temperature: float[20]
      time: float[1000]

---

Associating plottable data by name using the axes content attribute

Warning

Discouraged: See this method: Associating plottable data using content attributes applied to the NXdata group.

This method uses a content attribute of the content field with the data, called axes. The axes attribute contains the names of each dimension scale as a colon (or comma) separated list in the order they appear in C. For example:

denoting axes by name

  data:NXdata
    time_of_flight = 1500.0 1502.0 1504.0 ...
    polar_angle = 15.0 15.6 16.2 ...
    some_other_angle = 0.0 0.0 2.0 ...
    data = 5 7 14 ...
      @axes = ["polar_angle", "time_of_flight"]
      @signal = 1

---

Associating plottable data by dimension number using the axis content attribute

Warning

Discouraged: See this method: Associating plottable data by name using the axes content attribute

The original method uses a content attribute of each dimension scale content field called axis. It is an integer whose value is the number of the dimension, in order of fastest varying dimension. That is, if the array being stored is data with elements data[j][i] in C and data(i,j) in Fortran, where i is the time-of-flight index and j is the polar angle index, the NXdata group would contain:

denoting axes by integer number

  data:NXdata
    time_of_flight = 1500.0 1502.0 1504.0 ...
      @axis = 1
      @primary = 1
    polar_angle = 15.0 15.6 16.2 ...
      @axis = 2
      @primary = 1
    some_other_angle = 0.0 0.0 2.0 ...
      @axis = 1
    data = 5 7 14 ...
      @signal = 1

Each field of a dimension scale must have the NeXus attribute @axis. The primary attribute is unique to this method.

There are limited circumstances in which more than one dimension scale for the same data dimension can be included in the same NXdata group. The most common is when the dimension scales are the three components of an (hkl) scan. In order to handle this case, we have defined another NeXus attribute of type integer called primary whose value determines the order in which the scale is expected to be chosen for plotting, i.e.

• 1st choice: primary=1

• 2nd choice: primary=2

• etc.

If there is more than one scale with the same value of the axis content attribute, one of them must have set primary=1. Defining the primary attribute for the other scales is optional.

Note

The primary content attribute can only be

used with the first method of defining

dimension scales

discussed above. In addition to the signal data, this group could contain a data set of the same rank and dimensions called errors containing the standard deviations of the data.