4.3.1.12. NXdata

Status:

base class, extends NXobject

Description:

The NXdata class is designed to encapsulate all the information required for a set of data to be plotted. NXdata groups contain plottable data (sometimes referred to as signals or dependent variables) and their associated axis coordinates (sometimes referred to as axes or independent variables).

The actual names of the DATA and AXISNAME fields can be chosen freely, as indicated by the upper case (this is a common convention in all NeXus classes).

Note

NXdata provides data and coordinates to be plotted but does not describe how the data is to be plotted or even the dimensionality of the plot. https://www.nexusformat.org/NIAC2018Minutes.html#nxdata-plottype–attribute

Signals:

The DATA fields contain the signal values to be plotted. The name of the field to be used as the default plot signal is provided by the signal attribute. The names of the fields to be used as secondary plot signals are provided by the auxiliary_signals attribute.

An example with three signals, one of which being the default

data:NXdata
  @signal = "data1"
  @auxiliary_signals = ["data2", "data3"]
  data1: float[10,20,30]  --> the default signal
  data2: float[10,20,30]
  data3: float[10,20,30]

Axes:

The AXISNAME fields contain the axis coordinates associated with the data values. The names of all AXISNAME fields are listed in the axes attribute.

Rank

AXISNAME fields are typically one-dimensional arrays, which annotate one of the dimensions.

An example of this would be

data:NXdata
  @signal = "data"
  @axes = ["x", "y"]  --> the order matters
  data: float[10,20]
  x: float[10]        --> coordinates along the first dimension
  y: float[20]        --> coordinates along the second dimension

In this example each data point data[i,j] has axis coordinates [x[i], y[j]].

However, the fields can also have a rank greater than 1, in which case the rank of each AXISNAME must be equal to the number of data dimensions it spans.

An example of this would be

data:NXdata
  @signal = "data"
  @axes = ["x", "y"]  --> the order does NOT matter
  @x_indices = [0, 1]
  @y_indices = [0, 1]
  data: float[10,20]
  x: float[10,20]     --> coordinates along both dimensions
  y: float[10,20]     --> coordinates along both dimensions

In this example each data point data[i,j] has axis coordinates [x[i,j], y[i,j]].

Dimensions

The data dimensions annotated by an AXISNAME field are defined by the AXISNAME_indices attribute. When this attribute is missing, the position(s) of the AXISNAME string in the axes attribute are used.

When all AXISNAME fields are one-dimensional, and none of the data dimensions have more than one axis, the AXISNAME_indices attributes are often omitted. If one of the data dimensions has no AXISNAME field, the string “.” can be used in the corresponding index of the axes list.

An example of this would be

data:NXdata
  @signal = "data"
  @axes = ["x", ".", "z"]  --> the order matters
  data: float[10,20,30]
  x: float[10]             --> coordinates along the first dimension
  z: float[30]             --> coordinates along the third dimension

When using AXISNAME_indices this becomes

data:NXdata
  @signal = "data"
  @axes = ["x", "z"]       --> the order does NOT matter
  data: float[10,20,30]
  @x_indices = 0
  @z_indices = 2
  x: float[10]             --> coordinates along the first dimension
  z: float[30]             --> coordinates along the third dimension

When providing AXISNAME_indices attributes it is recommended to do it for all axes.

Non-trivial axes

What follows are two examples where AXISNAME_indices attributes cannot be omitted.

The first is an example where data dimensions have alternative axis coordinates. The NXdata group represents a stack of images collected at different energies. The wavelength is an alternative axis of energy for the last dimension (or vice versa).

data:NXdata
  @signal = "data"
  @axes = ["x", "y", "energy", "wavelength"]  --> the order does NOT matter
  @x_indices = 0
  @y_indices = 1
  @energy_indices = 2
  @wavelength_indices = 2
  data: float[10,20,30]
  x: float[10]              --> coordinates along the first dimension
  y: float[20]              --> coordinates along the second dimension
  energy: float[30]         --> coordinates along the third dimension
  wavelength: float[30]     --> coordinates along the third dimension

The second is an example with coordinates that span more than one dimension. The NXdata group represents data from 2D mesh scans performed at multiple energies. Each data point data[i,j,k] has axis coordinates [x[i,j,k], y[i,j,k], energy[k]].

data:NXdata
  @signal = "data"
  @axes = ["x", "y", "energy"]  --> the order does NOT matter
  @x_indices = [0, 1, 2]
  @y_indices = [0, 1, 2]
  @energy_indices = 2
  data: float[10,20,30]
  x: float[10,20,30]            --> coordinates along all dimensions
  y: float[10,20,30]            --> coordinates along all dimensions
  energy: float[30]             --> coordinates along the third dimension

Coordinate systems

The AXISNAME fields contain the axis coordinates associated with the data values in the data reference frame. Data is plotted in the plotting reference frame.

The active transformation matrix defines the coordinate transformation matrix from data reference frame to plotting reference frame in homogeneous coordinates. It is provided by the TRANSFORMATION field. When absent the identity matrix is assumed, meaning the data and plotting frame are identical.

The fields offset and scaling_factor provide additional coordinate transformations (offset and scaling) from data to plotting reference frame. They could be absorbed in the TRANSFORMATION field but if they are present they should be applied to the axis values before applying the activate transformation matrix.

Uncertainties:

Standard deviations on data values as well as coordinates can be provided by FIELDNAME_errors fields where FIELDNAME is the name of a DATA field or an AXISNAME field.

An example of uncertainties on the signal, auxiliary signals and axis coordinates

data:NXdata
  @signal = "data1"
  @auxiliary_signals = ["data2", "data3"]
  @axes = ["x", "z"]
  @x_indices = 0
  @z_indices = 2
  data1: float[10,20,30]
  data2: float[10,20,30]
  data3: float[10,20,30]
  x: float[10]
  z: float[30]
  data1_errors: float[10,20,30]
  data2_errors: float[10,20,30]
  data3_errors: float[10,20,30]
  x_errors: float[10]
  z_errors: float[30]

Symbols:

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

dataRank: rank of the DATA field(s)

nx: length of the x field

ny: length of the y field

nz: length of the z field

Groups cited:

none

Structure:

@signal: (optional) NX_CHAR

The value is the name of the signal that contains the default plottable data. This field or link must exist and be a direct child of this NXdata group.

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

@auxiliary_signals: (optional) NX_CHAR

Array of strings holding the names of additional signals to be plotted with the default signal. These fields or links must exist and be direct children of this NXdata group.

Each auxiliary signal needs to be of the same shape as the default signal.

@AXISNAME_indices: (optional) NX_INT

The AXISNAME_indices attribute is a single integer or an array of integers that defines which data dimension(s) are spanned by the corresponding axis. The first dimension index is 0 (zero).

When the AXISNAME_indices attribute is missing for an AXISNAME field, its value becomes the index (or indices) of the AXISNAME name in the axes attribute.

Note

When AXISNAME_indices contains multiple integers, it must be saved as an actual array of integers and not a comma separated string.

@axes: (optional) NX_CHAR

The axes attribute is a list of strings which are the names of the AXISNAME fields that contain the values of the coordinates along the data dimensions.

Note

When axes contains multiple strings, it must be saved as an actual array of strings and not a single comma separated string.

@active_transformation: (optional) NX_CHAR

The name of the field that contains the active transformation matrix.

AXISNAME: (optional) NX_NUMBER

Coordinate values along one or more data dimensions. The rank must be equal to the number of dimensions it spans.

As the upper case AXISNAME indicates, the names of the AXISNAME fields can be chosen freely. The axes attribute can be used to find all datasets in the NXdata that contain coordinate values.

@long_name: (optional) NX_CHAR

Axis label

@units: (optional) NX_CHAR

Unit in which the coordinate values are expressed. See the section NeXus Data Units for more information.

@distribution: (optional) NX_BOOLEAN

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

@first_good: (optional) NX_INT

Index of first good value

@last_good: (optional) NX_INT

Index of last good value

@axis: (optional) 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 attribute is now preferred.

DATA: (optional) NX_NUMBER (Rank: dataRank)

Data values to be used as the NeXus plottable data. As the upper case DATA indicates, the names of the DATA fields can be chosen freely. The signal attribute and auxiliary_signals attribute can be used to find all datasets in the NXdata that contain data values.

The maximum rank is 32 for compatibility with backend file formats.

@signal: (optional) 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: (optional) NX_CHAR

Defines the names of the coordinates (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.

@long_name: (optional) NX_CHAR

data label

FIELDNAME_errors: (optional) NX_NUMBER

“Errors” (meaning uncertainties or standard deviations) associated with any field named FIELDNAME in this NXdata group (e.g. an axis, signal or auxiliary signal).

The dimensions of the FIELDNAME_errors field must match the dimensions of the FIELDNAME field.

errors: (optional) NX_NUMBER (Rank: dataRank)

DEPRECATED: Use DATA_errors instead (NIAC2018)

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: (optional) 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: (optional) NX_FLOAT

An optional offset to apply to the values in data.

TRANSFORMATION: (optional) NX_FLOAT (Rank: 2)

The active transformation matrix in homogeneous coordinates. It is the matrix that transforms coordinates in the data reference frame into their corresponding coordinates in the plotting reference frame.

@transformation_type: (optional) NX_CHAR

The type of transformation may be helpful for plotting utilities.

Any of these values:

• identity

• translation

• proper rigid

• rigid

• similarity

• affine

• projective

title: (optional) NX_CHAR

Title for the plot.

x: (optional) NX_FLOAT (Rank: 1, Dimensions: [nx]) {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.

This is a special case of a AXISNAME field kept for backward compatiblity.

y: (optional) NX_FLOAT (Rank: 1, Dimensions: [ny]) {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.

This is a special case of a AXISNAME field kept for backward compatiblity.

z: (optional) NX_FLOAT (Rank: 1, Dimensions: [nz]) {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.

This is a special case of a AXISNAME field kept for backward compatiblity.

Hypertext Anchors

List of hypertext anchors for all groups, fields, attributes, and links defined in this class.

• /NXdata/AXISNAME-field

• /NXdata/AXISNAME@axis-attribute

• /NXdata/AXISNAME@distribution-attribute

• /NXdata/AXISNAME@first_good-attribute

• /NXdata/AXISNAME@last_good-attribute

• /NXdata/AXISNAME@long_name-attribute

• /NXdata/AXISNAME@units-attribute

• /NXdata/DATA-field

• /NXdata/DATA@axes-attribute

• /NXdata/DATA@long_name-attribute

• /NXdata/DATA@signal-attribute

• /NXdata/errors-field

• /NXdata/FIELDNAME_errors-field

• /NXdata/offset-field

• /NXdata/scaling_factor-field

• /NXdata/title-field

• /NXdata/TRANSFORMATION-field

• /NXdata/TRANSFORMATION@transformation_type-attribute

• /NXdata/x-field

• /NXdata/y-field

• /NXdata/z-field

• /NXdata@active_transformation-attribute

• /NXdata@auxiliary_signals-attribute

• /NXdata@axes-attribute

• /NXdata@AXISNAME_indices-attribute

• /NXdata@signal-attribute

NXDL Source:

https://github.com/nexusformat/definitions/blob/main/base_classes/NXdata.nxdl.xml