3.3.1.12. NXdataΒΆ

Status:

base class, extends NXobject, version 1.0

Description:

(required) NXdata describes the plottable data and related dimension scales.

It is mandatory that there is at least one NXdata group in each NXentry group. Note that the variable and data can be defined with different names. The signal and axes attributes of the data group define which items are plottable data and which are dimension scales, respectively.

NXdata is used to implement one of the basic motivations in NeXus, to provide a default plot for the data of this NXentry. The actual data might be stored in another group and (hard) linked to the NXdata group.

  • Each NXdata group will define only one data set containing plottable data, dimension scales, and possibly associated standard deviations. Other data sets may be present in the group.

  • The plottable data may be of arbitrary rank up to a maximum of NX_MAXRANK=32.

  • The plottable data will be named as the value of the group signal attribute, such as:

    data:NXdata
  @signal = "counts"
  @axes = "mr"
  @mr_indices = 0
  counts: float[100]  --> the default dependent data
  mr: float[100]  --> the default independent data

    The field named in the signal attribute must exist, either directly as a dataset or defined through a link.

  • The group axes attribute will name the dimension scale associated with the plottable data.

If available, the standard deviations of the data are to be stored in a data set of the same rank and dimensions, with the name errors.

  • For each data dimension, there should be a one-dimensional array of the same length.
  • These one-dimensional arrays are the dimension scales of the data, i.e. the values of the independent variables at which the data is measured, such as scattering angle or energy transfer.

The preferred method to associate each data dimension with its respective dimension scale is to specify the field name of each dimension scale in the group axes attribute as a string list. Here is an example for a 2-D data set data plotted against time, and pressure. (An additional temperature data set is provided and could be selected as an alternate for the pressure axis.):

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]

Old methods to identify the plottable data

There are two older methods of associating each data dimension to its respective dimension scale. Both are now out of date and should not be used when writing new data files. However, client software should expect to see data files written with any of these methods.

  • One method uses the axes attribute to specify the names of each dimension scale.
  • The oldest method uses the axis attribute on each dimension scale to identify with an integer the axis whose value is the number of the dimension.

Symbols:

These symbols will be used below to coordinate datasets with the same shape.

dataRank: rank of the data field

n: length of the variable field

nx: length of the x field

ny: length of the y field

nz: length of the z field

Groups cited:
none

Structure:

@signal: NX_CHAR

Declares which dataset is the default. The value is the name of the dataset to be plotted. A field of this name must exist (either as dataset or as a link to a dataset).

It is recommended (as of NIAC2014) to use this attribute rather than adding a signal attribute to the dataset. See http://wiki.nexusformat.org/2014_How_to_find_default_data for a summary of the discussion.

@axes: NX_CHAR

String array that defines the independent data fields used in the default plot for all of the dimensions of the signal field (the signal field is the field in this group that is named by the signal attribute of this group). 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 a field named AXISNAME_indices 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. Such as:

@I_axes="time", ".", "."

Since there are three items in the list, the the signal field must must be a three-dimensional array (rank=3). The first dimension is described by the values of a one-dimensional array named time while the other two dimensions have no fields to be used as dimension scales.

See examples provided on the NeXus wiki: http://wiki.nexusformat.org/2014_axes_and_uncertainties

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

@AXISNAME_indices: NX_CHAR

Each AXISNAME_indices attribute indicates the dependency relationship of the AXISNAME field (where AXISNAME is the name of a field that exists in this NXdata group) with one or more dimensions of the plottable data.

Integer array that defines the indices of the signal field (that field will be a multidimensional array) which need to be used in the AXISNAME dataset 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, , 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”.

Note

Attributes potentially containing multiple values (axes and _indices) are to be written as string or integer arrays, to avoid string parsing in reading applications.

variable[n]: NX_NUMBER

Dimension scale defining an axis of the data. Client is responsible for defining the dimensions of the data. The name of this field may be changed to fit the circumstances. Standard NeXus client tools will use the attributes to determine how to use this field.

@long_name: NX_CHAR

Axis label

@distribution: NX_BOOLEAN

0|false: single value, 1|true: multiple values

@first_good: NX_INT

Index of first good value

@last_good: NX_INT

Index of last good value

@axis: NX_POSINT

Index (positive integer) identifying this specific set of numbers.

N.B. The axis attribute is the old way of designating a link. Do not use the axes attribute with the axis attribute. The axes group attribute is now preferred.

variable_errors[n]: NX_NUMBER

Errors (uncertainties) associated with axis variable. Client is responsible for defining the dimensions of the data. The name of this field may be changed to fit the circumstances but is matched with the variable field with _errors appended.

data[n]: NX_NUMBER

This field contains the data values to be used as the NeXus plottable data. Client is responsible for defining the dimensions of the data. The name of this field may be changed to fit the circumstances. Standard NeXus client tools will use the attributes to determine how to use this field.

@signal: NX_POSINT

Plottable (independent) axis, indicate index number. Only one field in a NXdata group may have the signal=1 attribute. Do not use the signal attribute with the axis attribute.

@axes: NX_CHAR

Defines the names of the dimension scales (independent axes) for this data set as a colon-delimited array. NOTE: The axes attribute is the preferred method of designating a link. Do not use the axes attribute with the axis attribute.

@uncertainties: NX_CHAR

Specify the name (or names) of the uncertainties (errors) of the dependent axes as plottable data. NOTE: The uncertainties attribute uses the same syntax as the axes attribute, a string or an array of strings for multiple uncertainties.

Examples:

@I_uncertainties="Idev"

@Q_uncertainties="dQw", "dQl"

@long_name: NX_CHAR

data label

errors[n]: NX_NUMBER

Standard deviations of data values - the data array is identified by the group attribute signal. The errors array must have the same dimensions as data. Client is responsible for defining the dimensions of the data.

scaling_factor: NX_FLOAT

The elements in data are usually float values really. For efficiency reasons these are usually stored as integers after scaling with a scale factor. This value is the scale factor. It is required to get the actual physical value, when necessary.

offset: NX_FLOAT

An optional offset to apply to the values in data.

x[nx]: NX_FLOAT {units=NX_ANY}

This is an array holding the values to use for the x-axis of data. The units must be appropriate for the measurement.

y[ny]: NX_FLOAT {units=NX_ANY}

This is an array holding the values to use for the y-axis of data. The units must be appropriate for the measurement.

z[nz]: NX_FLOAT {units=NX_ANY}

This is an array holding the values to use for the z-axis of data. The units must be appropriate for the measurement.
NXDL Source:
https://github.com/nexusformat/definitions/blob/master/base_classes/NXdata.nxdl.xml