.. auto-generated by script ../../../../utils/nxdl2rst.py from the NXDL source NXdata.nxdl.xml .. index:: ! NXdata (base class) ! data (base class) see: data (base class); NXdata .. _NXdata: ====== NXdata ====== **Status**: base class, extends :ref:`NXobject` **Description**: :ref:`NXdata` describes the plottable data and related dimension scales. .. index:: plotting It is strongly recommended that there is at least one :ref:`NXdata` group in each :ref:`NXentry` group. Note that the fields named ``VARIABLE`` and ``DATA`` can be defined with different names. (Upper case is used to indicate that the actual name is left to the user.) The ``signal`` and ``axes`` attributes of the ``data`` group define which items are plottable data and which are *dimension scales*, respectively. :ref:`NXdata` is used to implement one of the basic motivations in NeXus, to provide a default plot for the data of this :ref:`NXentry`. The actual data might be stored in another group and (hard) linked to the :ref:`NXdata` group. * Each :ref:`NXdata` group will define one field as the default plottable data. The value of the ``signal`` attribute names this field. Additional fields may be used to describe the dimension scales and uncertainities. The ``auxiliary_signals`` attribute is a list of the other fields to be plotted with the ``signal`` data. * The plottable data may be of arbitrary rank up to a maximum of ``NX_MAXRANK=32`` (for compatibility with backend file formats). * 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 NeXus field 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. .. index:: link .. index:: axes (attribute) 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] .. rubric:: 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. .. index: !plot; axis label plot, axis units units dimension scale Each axis of the plot may be labeled with information from the dimension scale for that axis. The optional ``@long_name`` attribute is provided as the axis label default. If ``@long_name`` is not defined, then use the name of the dimension scale. A ``@units`` attribute, if available, may be added to the axis label for further description. See the section :ref:`Design-Units` for more information. .. index: !plot; axis title The optional ``title`` field, if available, provides a suggested title for the plot. If no ``title`` field is found in the :ref:`NXdata` group, look for a ``title`` field in the parent :ref:`NXentry` group, with a fallback to displaying the path to the :ref:`NXdata` group. NeXus is about how to find and annotate the data to be plotted but not to describe how the data is to be plotted. (https://www.nexusformat.org/NIAC2018Minutes.html#nxdata-plottype--attribute) **Symbols**: These symbols will be used below to coordinate fields 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**: .. _/NXdata@auxiliary_signals-attribute: .. index:: auxiliary_signals (file attribute) **@auxiliary_signals**: (optional) :ref:`NX_CHAR ` .. index:: plotting Array of strings holding the names of additional signals to be plotted with the default signal (specified by the ``signal`` attribute). Each auxiliary signal needs to be of the same shape as the default signal. .. NIAC2018: https://www.nexusformat.org/NIAC2018Minutes.html .. _/NXdata@signal-attribute: .. index:: signal (file attribute) **@signal**: (optional) :ref:`NX_CHAR ` .. index:: find the default plottable data .. index:: plotting .. index:: signal attribute value Declares which NeXus field is the default. The value is the name of the NeXus field to be plotted. (The value :ref:`names ` an existing child of this group. The child group must itself be a NeXus 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@axes-attribute: .. index:: axes (file attribute) **@axes**: (optional) :ref:`NX_CHAR ` .. index:: plotting 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:: @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: https://www.nexusformat.org/2014_axes_and_uncertainties.html If there are no axes at all (such as with a stack of images), the axes attribute can be omitted. .. _/NXdata@AXISNAME_indices-attribute: .. index:: AXISNAME_indices (file attribute) **@AXISNAME_indices**: (optional) :ref:`NX_INT ` 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* field 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, :math:`d(t,P)`, 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. .. _/NXdata/VARIABLE-field: .. index:: VARIABLE (field) **VARIABLE**: (optional) :ref:`NX_NUMBER ` (Rank: 1, Dimensions: [n]) 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. .. _/NXdata/VARIABLE@long_name-attribute: .. index:: long_name (field attribute) **@long_name**: (optional) :ref:`NX_CHAR ` Axis label .. _/NXdata/VARIABLE@distribution-attribute: .. index:: distribution (field attribute) **@distribution**: (optional) :ref:`NX_BOOLEAN ` ``0|false``: single value, ``1|true``: multiple values .. _/NXdata/VARIABLE@first_good-attribute: .. index:: first_good (field attribute) **@first_good**: (optional) :ref:`NX_INT ` Index of first good value .. _/NXdata/VARIABLE@last_good-attribute: .. index:: last_good (field attribute) **@last_good**: (optional) :ref:`NX_INT ` Index of last good value .. _/NXdata/VARIABLE@axis-attribute: .. index:: axis (field attribute) **@axis**: (optional) :ref:`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. .. _/NXdata/VARIABLE_errors-field: .. index:: VARIABLE_errors (field) **VARIABLE_errors**: (optional) :ref:`NX_NUMBER ` (Rank: 1, Dimensions: [n]) "Errors" (actually *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. This pattern of using ``VARIABLE_errors`` can be used throughout a NeXus data file to associate uncertainties with a field named ``VARIABLE``. This pattern also applies to other relationships such as ``VARIABLE_resolutions`` to connect additional data with a certain field. .. _/NXdata/DATA-field: .. index:: DATA (field) **DATA**: (optional) :ref:`NX_NUMBER ` (Rank: dataRank) .. index:: plotting 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. .. _/NXdata/DATA@signal-attribute: .. index:: signal (field attribute) **@signal**: (optional) :ref:`NX_POSINT ` .. 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 ` 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. .. _/NXdata/DATA@long_name-attribute: .. index:: long_name (field attribute) **@long_name**: (optional) :ref:`NX_CHAR ` data label .. _/NXdata/errors-field: .. index:: errors (field) **errors**: (optional) :ref:`NX_NUMBER ` (Rank: dataRank) 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 ` 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 `} This is an array holding the values to use for the x-axis of data. The units must be appropriate for the measurement. .. _/NXdata/y-field: .. index:: y (field) **y**: (optional) :ref:`NX_FLOAT ` (Rank: 1, Dimensions: [ny]) {units=\ :ref:`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. .. _/NXdata/z-field: .. index:: z (field) **z**: (optional) :ref:`NX_FLOAT ` (Rank: 1, Dimensions: [nz]) {units=\ :ref:`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. Hypertext Anchors ----------------- List of hypertext anchors for all groups, fields, attributes, and links defined in this class. * :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/offset-field ` * :ref:`/NXdata/scaling_factor-field ` * :ref:`/NXdata/title-field ` * :ref:`/NXdata/VARIABLE-field ` * :ref:`/NXdata/VARIABLE@axis-attribute ` * :ref:`/NXdata/VARIABLE@distribution-attribute ` * :ref:`/NXdata/VARIABLE@first_good-attribute ` * :ref:`/NXdata/VARIABLE@last_good-attribute ` * :ref:`/NXdata/VARIABLE@long_name-attribute ` * :ref:`/NXdata/VARIABLE_errors-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@signal-attribute ` **NXDL Source**: https://github.com/nexusformat/definitions/blob/main/base_classes/NXdata.nxdl.xml