diff --git a/base_classes/NXdata.nxdl.xml b/base_classes/NXdata.nxdl.xml index a9157ce5c2..b60075bc62 100644 --- a/base_classes/NXdata.nxdl.xml +++ b/base_classes/NXdata.nxdl.xml @@ -51,10 +51,10 @@ 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*)." + associated axis coordinates (sometimes referred to as *axes* or *independent variables*). The actual names of the :ref:`DATA </NXdata/DATA-field>` and :ref:`AXISNAME </NXdata/AXISNAME-field>` fields - can be chosen :ref:`freely <validItemName>`, as indicated by the upper case (this is a common convention in all NeXus classes). + can be chosen :ref:`freely <validItemName>`, 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. @@ -66,122 +66,168 @@ The :ref:`DATA </NXdata/DATA-field>` 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 </NXdata@signal-attribute>` attribute. - The names of the fields to be used as *secondary plot signals* are provided by the :ref:`auxiliary_signals</NXdata@auxiliary_signals-attribute>` attribute. - + The names of the fields to be used as *secondary plot signals* are provided by the + :ref:`auxiliary_signals</NXdata@auxiliary_signals-attribute>` 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 </NXdata/AXISNAME-field>` fields contain the axis coordinates associated with the data values. The names of all :ref:`AXISNAME </NXdata/AXISNAME-field>` - fields are listed in the :ref:`axes </NXdata@axes-attribute>` attribute. + The :ref:`AXISNAME </NXdata/AXISNAME-field>` fields contain the axis coordinates associated with the data values. + The names of all :ref:`AXISNAME </NXdata/AXISNAME-field>` fields are listed in the + :ref:`axes </NXdata@axes-attribute>` attribute. `Rank` - :ref:`AXISNAME </NXdata/AXISNAME-field>` fields are typically one-dimensional arrays, which annotate one of the dimensions. However, the fields can also have a rank greater than 1, - in which case the rank of each :ref:`AXISNAME </NXdata/AXISNAME-field>` must be equal to the number of data dimensions it spans. + :ref:`AXISNAME </NXdata/AXISNAME-field>` fields are typically one-dimensional arrays, which annotate one of the dimensions. - `Dimensions` + An example of this would be - The data dimensions annotated by an :ref:`AXISNAME </NXdata/AXISNAME-field>` field are defined by the :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attribute. - When this attribute is missing, the position(s) of the :ref:`AXISNAME </NXdata/AXISNAME-field>` string in the :ref:`axes </NXdata@axes-attribute>` attribute are used. + .. code-block:: - When all :ref:`AXISNAME </NXdata/AXISNAME-field>` fields are one-dimensional, and none of the data dimensions have more than one axis, the - :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes are often omitted. If one of the data dimensions has no :ref:`AXISNAME </NXdata/AXISNAME-field>` field, - the string “.” can be used in the corresponding index of the axes list. + 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 - When providing :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes it is recommended to do it for all axes. + In this example each data point ``data[i,j]`` has axis coordinates ``[x[i], y[j]]``. - **Uncertainties:** + However, the fields can also have a rank greater than 1, in which case the rank of each + :ref:`AXISNAME </NXdata/AXISNAME-field>` must be equal to the number of data dimensions it spans. - Standard deviations on data values as well as coordinates can be provided by :ref:`FIELDNAME_errors </NXdata/FIELDNAME_errors-field>` fields - where ``FIELDNAME`` is the name of a :ref:`DATA </NXdata/DATA-field>` field or an :ref:`AXISNAME </NXdata/AXISNAME-field>` field. + An example of this would be - **Examples:** + .. code-block:: - 1. Two-dimensional data with coordinates on both data dimensions:: - data:NXdata - @signal = "data" - @axes = ["y", "x"] --> the order does matter - data: float[10,20] --> the default signal - y: float[10] --> coordinates along the first dimension - x: float[20] --> coordinates along the second dimension + @signal = "data" + @axes = ["x", "y"] --> the order does NOT matters + data: float[10,20] + x: float[10,20] --> coordinates along both dimensions + y: float[10,20] --> coordinates along both dimension + + 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 </NXdata/AXISNAME-field>` field are defined by the + :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attribute. When this attribute is missing, + the position(s) of the :ref:`AXISNAME </NXdata/AXISNAME-field>` string in the + :ref:`axes </NXdata@axes-attribute>` attribute are used. + + When all :ref:`AXISNAME </NXdata/AXISNAME-field>` fields are one-dimensional, and none of the data dimensions + have more than one axis, the :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes + are often omitted. If one of the data dimensions has no :ref:`AXISNAME </NXdata/AXISNAME-field>` field, + the string “.” can be used in the corresponding index of the axes list. + + An example of this would be + + .. code-block:: - 2. Three-dimensional data with coordinates and uncertainties:: - data:NXdata - @signal = "data1" - @auxiliary_signals = ["data2", "data3"] - @axes = ["x", "z"] --> the order does NOT matter - @x_indices = 0 - @z_indices = 2 - data1: float[10,20,30] --> the default signal - data2: float[10,20,30] - data3: float[10,20,30] - x: float[10] --> coordinates along the first dimension - z: float[30] --> coordinates along the last dimension - 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] - - Note that the second data dimension has no coordinates. - - 3. An example with a data dimension with more than one axis:: + @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 </NXdata@AXISNAME_indices-attribute>` this becomes + + .. code-block:: data:NXdata - @signal = "data1" - @auxiliary_signals = ["data2", "data3"] - @axes = ["x", "y", "z", "time"] --> the order does NOT matter - @x_indices = 0 - @y_indices = 1 - @z_indices = 2 - @time_indices = 2 - data1: float[10,20,30] --> the default signal - data2: float[10,20,30] - data3: float[10,20,30] - x: float[10] --> coordinates along the first dimension - y: float[20] --> coordinates along the second dimension - z: float[30] --> coordinates along the last dimension - time: float[30] --> coordinates along the last dimension - - Note that ``time`` is an alternative axis of ``z`` for the last dimension (or vice versa). - - 4. An example with coordinates that span more than one data dimension:: - + @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 </NXdata@AXISNAME_indices-attribute>` attributes it is recommended + to do it for all axes. + + `Non-trivial axes` + + What follows are two examples where :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` 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 = "data1" - @auxiliary_signals = ["data2", "data3"] - @axes = ["x", "y", "z"] --> the order does NOT matter - @x_indices = [0, 1] - @y_indices = [0, 1] - @z_indices = 2 - data1: float[10,20,30] --> the default signal - data2: float[10,20,30] - data3: float[10,20,30] - x: float[10,20] --> coordinates along the first two dimensions - y: float[10,20] --> coordinates along the first two dimensions - z: float[30] --> coordinates along the last dimension - - Note that each signal value ``data1[i,j,k]`` has axis coordinates ``[x[i,j], y[i,j], z[k]]``. - The same goes for the auxiliary signals ``data2`` and ``data3``. - - 5. An example without :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes - and a data dimension without axis coordinates:: - + @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 = "data1" - @auxiliary_signals = ["data2", "data3"] - @axes = ["x", ".", "z"] --> the order matters - data1: float[10,20,30] --> the default signal - data2: float[10,20,30] - data3: float[10,20,30] - x: float[10] --> coordinates along the first dimension - z: float[30] --> coordinates along the last dimension + @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:** - This implicitely defines ``@x_indices = 0`` and ``@z_indices = 2``. Note that the second data dimension has no coordinates. + Standard deviations on data values as well as coordinates can be provided by + :ref:`FIELDNAME_errors </NXdata/FIELDNAME_errors-field>` fields where ``FIELDNAME`` is the name of a + :ref:`DATA </NXdata/DATA-field>` field or an :ref:`AXISNAME </NXdata/AXISNAME-field>` 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] @@ -192,7 +238,7 @@ .. index:: plotting .. index:: signal attribute value - The value is the :ref:`name <validItemName>` of the signal that contains + The value is the :ref:`name <validItemName>` of the signal that contains the default plottable data. This field or link *must* exist and be a direct child of this NXdata group. @@ -206,7 +252,7 @@ .. index:: plotting - Array of strings holding the :ref:`names <validItemName>` of additional + Array of strings holding the :ref:`names <validItemName>` of additional signals to be plotted with the :ref:`default signal </NXdata@signal-attribute>`. These fields or links *must* exist and be direct children of this NXdata group. @@ -251,7 +297,7 @@ Coordinate values along one or more :ref:`data </NXdata/DATA-field>` 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 <validItemName>`. + As the upper case ``AXISNAME`` indicates, the names of the ``AXISNAME`` fields can be chosen :ref:`freely <validItemName>`. The :ref:`axes </NXdata@axes-attribute>` attribute can be used to find all datasets in the ``NXdata`` that contain coordinate values. @@ -286,7 +332,7 @@ .. 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 <validItemName>`. The :ref:`signal attribute </NXdata@signal-attribute>` + indicates, the names of the ``DATA`` fields can be chosen :ref:`freely <validItemName>`. The :ref:`signal attribute </NXdata@signal-attribute>` and :ref:`auxiliary_signals attribute</NXdata@auxiliary_signals-attribute>` can be used to find all datasets in the ``NXdata`` that contain data values.