To: NIAC
From: H. J. Bernstein
Re: Proposed Revisions to Specification of Data Fields and
Data Attributes
As per recent discussions, these are rough draft revisions proposed to
section 1.3.1.2 and the first part of section 1.3.1.3 of the NeXus
design document.
The substance of the changes is the introduction of NX_... types for
data fields and arrays for attributes.
1.3.1.2. Data Fields
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). A data fields is
identified by a type and a their names. The type specifies the rules
for what may be stored in the data field. The name is arbitrary, but
must be unique within the group in which is stored. Previous versions
of NeXus used the name of a field to convey both the type of the field
and its name. While the use of names without types is deprecated,
when a name is used without a type, the name must, itself, be the name
of a field type. Some fields have engineering units to be specified.
In some cases, such in NXdetector/data, a field is expected to have be
an array of several dimensions. More than one field of the same type,
but with different names may be included in a given group.
Nexus-defined field types are prefixed by “NX_”.
Examples of data fields
In these examples, the field type and the type of the data in the
field are given in parenteses, separated by a colon.
variable (NX_VARIABLE:NX_NUMBER)
Dimension scale defining an axis of the data.
variable_errors (NX_VARIABLE_ERRORS:NX_NUMBER)
Errors (uncertainties) associated with axis variable.
wavelength (NX_WAVELENGTH:NX_FLOAT)
wavelength of radiation, units="NX_FLOAT"
chemical_formula (NX_CHEMICAL_FORMULA:NX_CHAR)
The chemical formula specified using CIF conventions.
name (NX_NAME:NX_CHAR)
Name of user responsible for this entry.
data (NX_DATA:[NX_NUMBER])
Data values from the detector, units="NX_ANY"
1.3.1.3. Data Attributes
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,
character strings, arrays of numbers or character strings. Arrays of
character strings should be used in preference to colon- or
comma-separated lists of strings In addition, NeXus uses attributes
to identify plottable data and their axes, etc. A description of some
of the many possible attributes can be found in the next table:
Examples of data attributes
units (NX_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_SIGNAL:NX_POSINT)
Defines which data set contains the signal to be plotted, use
signal=1:NX_SIGNAL for main signal, signal=2:NX_SIGNAL for a second
item to plot, and so on.
axes (NX_AXES:[NX_CHAR])
axes:NX_AXES defines the names of the dimension scales for this
data set as an array. Note that some legacy data files may use a
comma-separated list or colon-separated list.
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”]:NX_axes in addition to an
attribute signal=1:NX_SIGNAL.
axis (NX_AXIS:NX_POSINT)
The original way of designating data for plotting, now superceded
by the axes:NX_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:NX_DATA,
with elements data[j][i] in C and data(i,j) in Fortran, axis would
have the following values: ith dimension (axis=1:NXAXIS), jth
dimension (axis=2:NXAXIS), etc.
primary (NX_PRIMARY:NX_POSINT)
Defines the order of preference for dimension scales which apply
to the same rank of signal data. Use primary=1:NX_PRIMARY to indicate
preferred dimension scale
long_name (NX_LONG_NAME:NX_CHAR)
Defines title of signal data or axis label of dimension scale
calibration_status (NX_CALIBRATION_STATUS:NX_CHAR)
Defines status of data value - set to Nominal or Measured
offset (NX_OFFSET:[NX_INT])
Rank values of offsets to use for each dimension if the data is
not in C storage order
stride (NX_STRIDE:[NX_INT])
Rank values of steps to use when incrementing the dimension
vector (NX_VECTOR:[NX_FLOAT])
3 values describing the axis of rotation or the direction of translation
interpretation (NX_INTERPRETATION:NX_CHAR)
Describes how to display the data. Allowed values include:
· scaler (0-D data)
· spectrum (1-D data)
· image (2-D data)
· vertex (3-D data)