3.3.1.12. NXdata

Status:

base class, extends NXobject

Description:

The :ref:`NXdata` class is designed to encapsulate all the information required ...

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

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 :ref:`name ` of the signal that contains ...

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 :ref:`names ` of additional ...

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.

@default_slice: (optional) NX_CHAR_OR_NUMBER

Which slice of data to show in a plot by default. This is useful especially fo ...

Which slice of data to show in a plot by default. This is useful especially for datasets with more than 2 dimensions.

Should be an array of length equal to the number of dimensions in the data, with the following possible values:

• “.”: All the data in this dimension should be included

• Integer: Only this slice should be used.

• String: Only this slice should be used. Use if AXISNAME is a string array.

Example:

data:NXdata
      @signal = "data"
      @axes = ["image_id", "channel", ".", "."]
      @image_id_indices = 0
      @channel_indices = 1
      @default_slice = [".", "difference", ".", "."]
      image_id = [1, ..., nP]
      channel = ["threshold_1", "threshold_2", "difference"]
      data = uint[nP, nC, i, j]

Here, a data array with four dimensions, including the number of images (nP) and number of channels (nC), specifies more dimensions than can be visualized with a 2D image viewer for a given image. Therefore the default_slice attribute specifies that the “difference” channel should be shown by default.

Alternate version using an integer would look like this (note 2 is a string):

data:NXdata
      @signal = "data"
      @axes = ["image_id", "channel", ".", "."]
      @image_id_indices = 0
      @channel_indices = 1
      @default_slice = [".", "2", ".", "."]
      image_id = [1, ..., nP]
      channel = ["threshold_1", "threshold_2", "difference"]
      data = uint[nP, nC, i, j]

@AXISNAME_indices: (optional) NX_INT

The ``AXISNAME_indices`` attribute is a single integer or an array of integers ...

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 :ref:`A ...

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.

AXISNAME: (optional) NX_CHAR_OR_NUMBER

Coordinate values along one or more :ref:`data ` dimension ...

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.

Most AXISNAME fields will be sequences of numbers but if an axis is better represented using names, such as channel names, an array of NX_CHAR can be provided.

@long_name: (optional) NX_CHAR

Axis label

@units: (optional) NX_CHAR

Unit in which the coordinate values are expressed. ...

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, ...

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. ...

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 ...

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. ...

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 ...

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*) ...

“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 - ...

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.

FIELDNAME_scaling_factor: (optional) NX_NUMBER

An optional scaling factor to apply to the values in any field named ``FIELDNA ...

An optional scaling factor to apply to the values in any field named FIELDNAME in this NXdata group. This can be a DATA field (signal or auxiliary signal) or a AXISNAME field (axis).

The elements stored in NXdata datasets are often stored as integers for efficiency reasons and need further correction or conversion, generating floats. For example, raw values could be stored from a device that need to be converted to values that represent the physical values. The two fields FIELDNAME_scaling_factor and FIELDNAME_offset allow linear corrections using the following convention:

corrected values = (FIELDNAME + offset) * scaling_factor

This formula will derive the values to use in downstream applications, when necessary.

When omitted, the scaling factor is assumed to be 1.

FIELDNAME_offset: (optional) NX_NUMBER

An optional offset to apply to the values in FIELDNAME (usually the signal). ...

An optional offset to apply to the values in FIELDNAME (usually the signal).

When omitted, the offset is assumed to be 0.

See FIELDNAME_scaling_factor for more information.

scaling_factor: (optional) NX_FLOAT

DEPRECATED: Use FIELDNAME_scaling_factor instead

The scaling_factor and FIELDNAME_scaling_factor fields have similar semantics. ...

The scaling_factor and FIELDNAME_scaling_factor fields have similar semantics. However, scaling_factor is ambiguous in the case of multiple signals. Therefore scaling_factor is deprecated. Use FIELDNAME_scaling_factor instead, even when only a single signal is present.

offset: (optional) NX_FLOAT

DEPRECATED: Use FIELDNAME_offset instead

The offset and FIELDNAME_offset fields have similar semantics. ...

The offset and FIELDNAME_offset fields have similar semantics. However, offset is ambiguous in the case of multiple signals. Therefore offset is deprecated. Use FIELDNAME_offset instead, even when only a single signal is present.

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 ...

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 ...

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 ...

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/FIELDNAME_offset-field

• /NXdata/FIELDNAME_scaling_factor-field

• /NXdata/offset-field

• /NXdata/scaling_factor-field

• /NXdata/title-field

• /NXdata/x-field

• /NXdata/y-field

• /NXdata/z-field

• /NXdata@auxiliary_signals-attribute

• /NXdata@axes-attribute

• /NXdata@AXISNAME_indices-attribute

• /NXdata@default_slice-attribute

• /NXdata@signal-attribute

NXDL Source:

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