.. auto-generated by script ../../../../utils/nxdl2rst.py from the NXDL source ../../../../base_classes/NXdata.nxdl.xml

.. index::
    ! NXdata (base class)
    ! data (base class)
    see: data (base class); NXdata

.. _NXdata:

======
NXdata
======

**Status**:

  base class, extends :ref:`NXobject`, version 1.0

**Description**:

  .. index:: plotting

  (**required**) ``NXdata`` is a template of 
  plottable data and their dimension scales. 
  It is mandatory  that there is at least one ``NXdata`` group 
  in each NXentry group.  
  Note that the ``variable`` and ``data`` 
  can be defined with different names.  
  The ``signal`` and ``axes`` attribute of the 
  ``data`` item define which items 
  are plottable data and which are *dimension scales*.

  * Each ``NXdata`` group will consist of only one data set
    containing plottable data and their standard deviations.
  * This data set may be of arbitrary rank up to a maximum
    of ``NX_MAXRANK=32``.
  * The plottable data will be identified by the attribute:
    ``signal=1``
  * The plottable data will identify the *dimension scale* 
    specification(s) in the ``axes`` attribute.

  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

  There are two methods of linking 
  each data dimension to its respective dimension scale.

  .. index:: axes (attribute)

  The preferred (and recommended) method uses the ``axes`` 
  attribute to specify the names of each *dimension scale*.

  The older method uses the ``axis`` attribute on each
  *dimension scale*
  to identify
  with an integer the axis whose value is the number of the dimension.

  ``NXdata`` is used to implement one of the basic motivations in NeXus,
  to provide a default plot for the data of this ``NXentry``.  The actual data
  might be stored in another group and (hard) linked to the ``NXdata`` group.

**Symbols**:

  These symbols will be used below to coordinate datasets 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**:

  .. index:: variable (data field)

  **variable[n]**: :ref:`NX_NUMBER <NX_NUMBER>`

    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.

    .. index:: long_name (attribute)

    **@long_name**: :ref:`NX_CHAR <NX_CHAR>`

      Axis label

    .. index:: distribution (attribute)

    **@distribution**: :ref:`NX_BOOLEAN <NX_BOOLEAN>`

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

    .. index:: first_good (attribute)

    **@first_good**: :ref:`NX_INT <NX_INT>`

      Index of first good value

    .. index:: last_good (attribute)

    **@last_good**: :ref:`NX_INT <NX_INT>`

      Index of last good value

    .. index:: axis (attribute)

    **@axis**: :ref:`NX_POSINT <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.

  .. index:: variable_errors (data field)

  **variable_errors[n]**: :ref:`NX_NUMBER <NX_NUMBER>`

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

  .. index:: data (data field)

  **data[n]**: :ref:`NX_NUMBER <NX_NUMBER>`

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

    .. index:: signal (attribute)

    **@signal**: :ref:`NX_POSINT <NX_POSINT>`

      .. index:: plotting

      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.

    .. index:: axes (attribute)

    **@axes**: :ref:`NX_CHAR <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.

    .. index:: uncertainties (attribute)

    **@uncertainties**: :ref:`NX_CHAR <NX_CHAR>`

      Specify the names of the errors (uncertainties) 
      of the dependent axes as plottable data.
      NOTE: The ``errors`` attribute uses the same syntax
      as the ``axes`` attribute.

    .. index:: long_name (attribute)

    **@long_name**: :ref:`NX_CHAR <NX_CHAR>`

      data label

  .. index:: errors (data field)

  **errors[n]**: :ref:`NX_NUMBER <NX_NUMBER>`

    Standard deviations of data values - 
    the data array is identified by the attribute ``signal=1``. 
    The ``errors`` array must have the same dimensions as ``data``.
    Client is responsible for defining the dimensions of the data.

  .. index:: scaling_factor (data field)

  **scaling_factor**: :ref:`NX_FLOAT <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.

  .. index:: offset (data field)

  **offset**: :ref:`NX_FLOAT <NX_FLOAT>`

    An optional offset to apply to the values in data.

  .. index:: x (data field)

  **x[nx]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANY <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.

  .. index:: y (data field)

  **y[ny]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANY <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.

  .. index:: z (data field)

  **z[nz]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANY <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.

**Source**:
  Automatically generated from https://github.com/nexusformat/definitions/blob/master/base_classes/NXdata.nxdl.xml