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–attributeSignals:
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 dimensionIn 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 dimensionsIn 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 dimensionWhen 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 dimensionWhen 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 ofenergy
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 dimensionThe 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 dimensionUncertainties:
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
fieldny: length of the
y
fieldnz: 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 is0
(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 theAXISNAME
fields can be chosen freely. The axes attribute can be used to find all datasets in theNXdata
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
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 theDATA
fields can be chosen freely. The signal attribute and auxiliary_signals attribute can be used to find all datasets in theNXdata
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 thesignal
attribute with theaxis
attribute.@axes: (optional) NX_CHAR
@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 thisNXdata
group (e.g. an axis, signal or auxiliary signal).The dimensions of the
FIELDNAME_errors
field must match the dimensions of theFIELDNAME
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
. Theerrors
array must have the same dimensions asDATA
. 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 ...
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.
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.