.. auto-generated by dev_tools.docs.nxdl from the NXDL source base_classes/NXdata.nxdl.xml -- DO NOT EDIT .. index:: ! NXdata (base class) ! data (base class) see: data (base class); NXdata .. _NXdata: ====== NXdata ====== .. Contributors List .. |contrib_name| replace:: Woutdenolf|woutdenolf|https://avatars.githubusercontent.com/u/7264703?v=4|2023-10-06 .. |contrib_name| replace:: Peter Chang|PeterC-DLS|https://avatars.githubusercontent.com/u/1381719?v=4|2022-09-28 .. |contrib_name| replace:: Pete R Jemian|prjemian|https://avatars.githubusercontent.com/u/2279984?v=4|2022-06-13 .. |contrib_name| replace:: Sophie Hotz|soph-dec|https://avatars.githubusercontent.com/u/73243774?v=4|2021-08-18 **Status**: base class, extends :ref:`NXobject` **Description**: .. collapse:: The :ref:`NXdata` class is designed to encapsulate all the information required ... The :ref:`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 :ref:`DATA ` and :ref:`AXISNAME ` fields can be chosen :ref:`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:** .. index:: plotting The :ref:`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 :ref:`signal ` attribute. The names of the fields to be used as *secondary plot signals* are provided by the :ref:`auxiliary_signals` attribute. An example with three signals, one of which being the default .. code-block:: 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:** .. index:: axes (attribute) .. index:: coordinates The :ref:`AXISNAME ` fields contain the axis coordinates associated with the data values. The names of all :ref:`AXISNAME ` fields are listed in the :ref:`axes ` attribute. `Rank` :ref:`AXISNAME ` fields are typically one-dimensional arrays, which annotate one of the dimensions. An example of this would be .. code-block:: 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 :ref:`AXISNAME ` must be equal to the number of data dimensions it spans. An example of this would be .. code-block:: 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 :ref:`AXISNAME ` field are defined by the :ref:`AXISNAME_indices ` attribute. When this attribute is missing, the position(s) of the :ref:`AXISNAME ` string in the :ref:`axes ` attribute are used. When all :ref:`AXISNAME ` fields are one-dimensional, and none of the data dimensions have more than one axis, the :ref:`AXISNAME_indices ` attributes are often omitted. If one of the data dimensions has no :ref:`AXISNAME ` field, the string “.” can be used in the corresponding index of the axes list. An example of this would be .. code-block:: 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 :ref:`AXISNAME_indices ` this becomes .. code-block:: 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 :ref:`AXISNAME_indices ` attributes it is recommended to do it for all axes. `Non-trivial axes` What follows are two examples where :ref:`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). .. code-block:: 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]]``. .. code-block:: 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 :ref:`FIELDNAME_errors ` fields where ``FIELDNAME`` is the name of a :ref:`DATA ` field or an :ref:`AXISNAME ` field. An example of uncertainties on the signal, auxiliary signals and axis coordinates .. code-block:: 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**: .. _/NXdata@signal-attribute: .. index:: signal (file attribute) **@signal**: (optional) :ref:`NX_CHAR ` .. collapse:: The value is the :ref:`name ` of the signal that contains ... .. index:: find the default plottable data .. index:: plotting .. index:: signal attribute value The value is the :ref:`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. .. _/NXdata@auxiliary_signals-attribute: .. index:: auxiliary_signals (file attribute) **@auxiliary_signals**: (optional) :ref:`NX_CHAR ` .. collapse:: Array of strings holding the :ref:`names ` of additional ... .. index:: plotting Array of strings holding the :ref:`names ` of additional signals to be plotted with the :ref:`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. .. NIAC2018: https://www.nexusformat.org/NIAC2018Minutes.html .. _/NXdata@default_slice-attribute: .. index:: default_slice (file attribute) **@default_slice**: (optional) :ref:`NX_CHAR_OR_NUMBER ` .. collapse:: 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] .. _/NXdata@AXISNAME_indices-attribute: .. index:: AXISNAME_indices (file attribute) **@AXISNAME_indices**: (optional) :ref:`NX_INT ` .. collapse:: 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 :ref:`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 :ref:`AXISNAME ` field, its value becomes the index (or indices) of the :ref:`AXISNAME ` name in the :ref:`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. .. _/NXdata@axes-attribute: .. index:: axes (file attribute) **@axes**: (optional) :ref:`NX_CHAR ` .. collapse:: The ``axes`` attribute is a list of strings which are the names of the :ref:`A ... .. index:: plotting The ``axes`` attribute is a list of strings which are the names of the :ref:`AXISNAME ` fields that contain the values of the coordinates along the :ref:`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. .. _/NXdata/AXISNAME-field: .. index:: AXISNAME (field) **AXISNAME**: (optional) :ref:`NX_CHAR_OR_NUMBER ` .. collapse:: Coordinate values along one or more :ref:`data ` dimension ... Coordinate values along one or more :ref:`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 :ref:`freely `. The :ref:`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. .. _/NXdata/AXISNAME@long_name-attribute: .. index:: long_name (field attribute) **@long_name**: (optional) :ref:`NX_CHAR ` Axis label .. _/NXdata/AXISNAME@units-attribute: .. index:: units (field attribute) **@units**: (optional) :ref:`NX_CHAR ` .. collapse:: Unit in which the coordinate values are expressed. ... Unit in which the coordinate values are expressed. See the section :ref:`Design-Units` for more information. .. _/NXdata/AXISNAME@distribution-attribute: .. index:: distribution (field attribute) **@distribution**: (optional) :ref:`NX_BOOLEAN ` .. collapse:: ``0|false``: single value, ... ``0|false``: single value, ``1|true``: multiple values .. _/NXdata/AXISNAME@first_good-attribute: .. index:: first_good (field attribute) **@first_good**: (optional) :ref:`NX_INT ` Index of first good value .. _/NXdata/AXISNAME@last_good-attribute: .. index:: last_good (field attribute) **@last_good**: (optional) :ref:`NX_INT ` Index of last good value .. _/NXdata/AXISNAME@axis-attribute: .. index:: axis (field attribute) **@axis**: (optional) :ref:`NX_POSINT ` .. collapse:: 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 :ref:`axes ` attribute with the ``axis`` attribute. The :ref:`axes ` attribute is now preferred. .. _/NXdata/DATA-field: .. index:: DATA (field) **DATA**: (optional) :ref:`NX_NUMBER ` (Rank: dataRank) .. collapse:: Data values to be used as the NeXus *plottable data*. As the upper case ``DATA ... .. index:: plotting 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 :ref:`freely `. The :ref:`signal attribute ` and :ref:`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. .. _/NXdata/DATA@signal-attribute: .. index:: signal (field attribute) **@signal**: (optional) :ref:`NX_POSINT ` .. collapse:: Plottable (independent) axis, indicate index number. ... .. index:: plotting Plottable (independent) axis, indicate index number. Only one field in a :ref:`NXdata` group may have the ``signal=1`` attribute. Do not use the ``signal`` attribute with the ``axis`` attribute. .. _/NXdata/DATA@axes-attribute: .. index:: axes (field attribute) **@axes**: (optional) :ref:`NX_CHAR ` .. collapse:: 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 :ref:`axes ` attribute is the preferred method of designating a link. Do not use the :ref:`axes ` attribute with the ``axis`` attribute. .. _/NXdata/DATA@long_name-attribute: .. index:: long_name (field attribute) **@long_name**: (optional) :ref:`NX_CHAR ` data label .. _/NXdata/FIELDNAME_errors-field: .. index:: FIELDNAME_errors (field) **FIELDNAME_errors**: (optional) :ref:`NX_NUMBER ` .. collapse:: "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. .. _/NXdata/errors-field: .. index:: errors (field) **errors**: (optional) :ref:`NX_NUMBER ` (Rank: dataRank) .. index:: deprecated **DEPRECATED**: Use ``DATA_errors`` instead (NIAC2018) .. collapse:: 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. .. _/NXdata/scaling_factor-field: .. index:: scaling_factor (field) **scaling_factor**: (optional) :ref:`NX_FLOAT ` .. collapse:: 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. .. _/NXdata/offset-field: .. index:: offset (field) **offset**: (optional) :ref:`NX_FLOAT ` An optional offset to apply to the values in data. .. _/NXdata/title-field: .. index:: title (field) **title**: (optional) :ref:`NX_CHAR ` Title for the plot. .. _/NXdata/x-field: .. index:: x (field) **x**: (optional) :ref:`NX_FLOAT ` (Rank: 1, Dimensions: [nx]) {units=\ :ref:`NX_ANY `} .. collapse:: 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 :ref:`AXISNAME field ` kept for backward compatiblity. .. _/NXdata/y-field: .. index:: y (field) **y**: (optional) :ref:`NX_FLOAT ` (Rank: 1, Dimensions: [ny]) {units=\ :ref:`NX_ANY `} .. collapse:: 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 :ref:`AXISNAME field ` kept for backward compatiblity. .. _/NXdata/z-field: .. index:: z (field) **z**: (optional) :ref:`NX_FLOAT ` (Rank: 1, Dimensions: [nz]) {units=\ :ref:`NX_ANY `} .. collapse:: 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 :ref:`AXISNAME field ` kept for backward compatiblity. Hypertext Anchors ----------------- List of hypertext anchors for all groups, fields, attributes, and links defined in this class. * :ref:`/NXdata/AXISNAME-field ` * :ref:`/NXdata/AXISNAME@axis-attribute ` * :ref:`/NXdata/AXISNAME@distribution-attribute ` * :ref:`/NXdata/AXISNAME@first_good-attribute ` * :ref:`/NXdata/AXISNAME@last_good-attribute ` * :ref:`/NXdata/AXISNAME@long_name-attribute ` * :ref:`/NXdata/AXISNAME@units-attribute ` * :ref:`/NXdata/DATA-field ` * :ref:`/NXdata/DATA@axes-attribute ` * :ref:`/NXdata/DATA@long_name-attribute ` * :ref:`/NXdata/DATA@signal-attribute ` * :ref:`/NXdata/errors-field ` * :ref:`/NXdata/FIELDNAME_errors-field ` * :ref:`/NXdata/offset-field ` * :ref:`/NXdata/scaling_factor-field ` * :ref:`/NXdata/title-field ` * :ref:`/NXdata/x-field ` * :ref:`/NXdata/y-field ` * :ref:`/NXdata/z-field ` * :ref:`/NXdata@auxiliary_signals-attribute ` * :ref:`/NXdata@axes-attribute ` * :ref:`/NXdata@AXISNAME_indices-attribute ` * :ref:`/NXdata@default_slice-attribute ` * :ref:`/NXdata@signal-attribute ` **NXDL Source**: https://github.com/nexusformat/definitions/blob/main/base_classes/NXdata.nxdl.xml