diff --git a/applications/NXcanSAS.nxdl.xml b/applications/NXcanSAS.nxdl.xml index e562257c4d..6ff164f6ad 100644 --- a/applications/NXcanSAS.nxdl.xml +++ b/applications/NXcanSAS.nxdl.xml @@ -1215,7 +1215,7 @@ - the wavelengths field (as a dimension scale) corresponding to this transmission + the wavelengths field (as coordinates) corresponding to this transmission diff --git a/base_classes/NXdata.nxdl.xml b/base_classes/NXdata.nxdl.xml index 774c653253..8533bdb804 100644 --- a/base_classes/NXdata.nxdl.xml +++ b/base_classes/NXdata.nxdl.xml @@ -42,36 +42,134 @@ These symbols will be used below to coordinate fields with the same shape. - rank of the ``DATA`` field - length of the ``AXISNAME`` field + rank of the ``DATA`` field(s) length of the ``x`` field length of the ``y`` field length of the ``z`` field - - - .. index:: plotting - - Array of strings holding the :ref:`names <validItemName>` of additional - signals to be plotted with the default :ref:`signal </NXdata@signal-attribute>`. - 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 - - + + :ref:`NXdata` is used to implement one of the basic motivations of NeXus: to provide a default plot associated + to a NeXus group such as an :ref:`NXentry` group. :ref:`NXdata` describes plottable data (also referred to as + *signals* or *dependent variables*) and associated coordinates (also 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 defined freely, as indicated by the upper case (this is a common convention in all NeXus classes). + + **Signals:** + + .. index:: plotting + + 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. + + .. index:: axes (attribute) + .. index:: coordinates + + **Axes:** + + The :ref:`AXISNAME </NXdata/AXISNAME-field>` fields contain the coordinates associated to the ref:`data </NXdata/DATA-field>` values. + The names of the fields to be used as coordinates are provided by the :ref:`axes </NXdata@axes-attribute>` attribute. + One `AXISNAME </NXdata/AXISNAME-field>` field provides the coordinates along one or more :ref:`data </NXdata/DATA-field>` dimensions. The + rank of an `AXISNAME </NXdata/AXISNAME-field>` field is equal to the number of :ref:`data </NXdata/DATA-field>` dimensions it spans. + + The :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes define the :ref:`DATA </NXdata/DATA-field>` dimensions spanned + by the corresponding :ref:`AXISNAME </NXdata/AXISNAME-field>` fields. When the :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes + are missing, they are considered to be equal to the index of the :ref:`AXISNAME </NXdata/AXISNAME-field>` name in the :ref:`axes </NXdata@axes-attribute>` attribute. + + The ``AXISNAME_indices`` attributes are to be provided if the indices cannot be unambiguously derived from the names in the + :ref:`axes </NXdata@axes-attribute>` attribute. This is the case when an :ref:`AXISNAME </NXdata/AXISNAME-field>` + field spans more than one :ref:`data </NXdata/DATA-field>` dimension or when a :ref:`data </NXdata/DATA-field>` dimension + is covered by more than one :ref:`AXISNAME </NXdata/AXISNAME-field>`. + + Either all :ref:`AXISNAME </NXdata/AXISNAME-field>` fields have a corresponding ``AXISNAME_indices`` attribute or none have. + + **Uncertainties:** + + 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. + + **Examples:** + + 1. Coordinates implicitly assigned to data dimensions:: + + 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 + + This implicitely defines `x_indices = 0` and `z_indices = 2`. + + 2. Coordinates explicitly assigned to data dimensions:: + + data:NXdata + @signal="data1" + @auxiliary_signals = ["data2", "data3"] + @axes=["x", "y", "z", "time"] --> the order does NOT matters + data1: float[10,20,30] --> the default signal + data2: float[10,20,30] + 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 + x_indices: 0 + y_indices: 1 + z_indices: 2 + time_indices: 2 + + 3. Coordinates that span more than one data dimension:: + + data:NXdata + @signal="data1" + @auxiliary_signals = ["data2", "data3"] + @@axes=["x", "y", "z"] --> the order does NOT matters + 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 + + 4. Uncertainties on coordinates and signal values:: + + data:NXdata + @signal="data1" + @auxiliary_signals = ["data2", "data3"] + @axes=["x", ".", "z"] + 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] + + .. 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 + + + .. index:: find the default plottable data .. index:: plotting .. index:: signal attribute value - Declares which NeXus field is the default. - The value is the :ref:`name <validItemName>` of the data field to be plotted. - This field or link *must* exist and be a direct child of this NXdata group. + 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. It is recommended (as of NIAC2014) to use this attribute rather than adding a signal attribute to the field. @@ -79,40 +177,40 @@ for a summary of the discussion. - + .. index:: plotting - Array of strings holding the :ref:`names <validItemName>` of - the independent data fields used in the default plot for all of - the dimensions of the :ref:`signal </NXdata@signal-attribute>` - as well as any :ref:`auxiliary signals </NXdata@auxiliary_signals-attribute>`. - - One name is provided for every dimension in the *signal* or *auxiliary signal* fields. - - The *axes* values are the names of fields or links that *must* exist and be direct - children of this NXdata group. - - 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:: + 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. - @axes=["time", ".", "."] + Each auxiliary signal needs to be of the same shape as the default signal. - Since there are three items in the list, the *signal* field - 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. + .. NIAC2018: + https://www.nexusformat.org/NIAC2018Minutes.html + + + + + .. index:: plotting - See examples provided on the NeXus wiki: - https://www.nexusformat.org/2014_axes_and_uncertainties.html + The ``axes`` attribute is a list of strings which are the names of the :ref:`AXISNAME </NXdata/AXISNAME-field>` fields + that contain the values of the coordinates along the :ref:`data </NXdata/DATA-field>` dimensions. - If there are no axes at all (such as with a stack of images), + This list of strings is either an *ordered sequence* or an *unordered* set, depending on whether each :ref:`AXISNAME </NXdata/AXISNAME-field>` + field has a corresponding :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attribute or not. + + When the list of strings is an *ordered sequence*, the index of :ref:`AXISNAME </NXdata/AXISNAME-field>` in this list + defines the :ref:`data </NXdata/DATA-field>` dimension to which this axis belongs. The string ``"."`` can be used when there are no + coordinates provided for a :ref:`data </NXdata/DATA-field>` dimension. If there are no coordinates at all (such as with a stack of images), the axes attribute can be omitted. + + Either all :ref:`AXISNAME </NXdata/AXISNAME-field>` fields have a corresponding :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` + attribute or none have. + + .. note:: When ``axes`` contains multiple strings, it must be saved as an actual array + of strings and not a single comma separated string. @@ -122,172 +220,39 @@ --> - 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. - - - - - :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 ``AXISNAME`` 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. + The ``AXISNAME_indices`` attribute is a single integer or an array of integers that defines which :ref:`data </NXdata/DATA-field>` + dimension(s) are spanned by the corresponding axis. The first dimension index is ``0`` (zero). - .. index: !plot; axis label - plot, axis units - units - dimension scale + When each :ref:`AXISNAME </NXdata/AXISNAME-field>` field has a corresponding ``AXISNAME_indices`` attribute, + the :ref:`axes </NXdata@axes-attribute>` attribute becomes an *unordered set* of axis names. - 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. + When the ``AXISNAME_indices`` attributes are missing, the value of each ``AXISNAME_indices`` is the index of + ``AXISNAME`` in the *ordered list* of axis names provided by the :ref:`axes </NXdata@axes-attribute>` attribute. - .. index: !plot; axis title + Either all :ref:`AXISNAME </NXdata/AXISNAME-field>` fields have a corresponding ``AXISNAME_indices`` attribute or none have. - 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) - + .. note:: When ``AXISNAME_indices`` contains multiple integers, it must be saved as an actual array + of integers and not a comma separated string. + + + + - 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. - - + Coordinate values along one or more :ref:`data </NXdata/DATA-field>` dimensions. The rank of ``AXISNAME`` + is equal to the number of :ref:`data </NXdata/DATA-field>` dimensions it spans (so at least ``1``). + + As the upper case ``AXISNAME`` indicates, the names of the ``AXISNAME`` fields can be chosen freely. + The :ref:`axes </NXdata@axes-attribute>` attribute can be used to find all datasets in the + ``NXdata`` that contain coordinate values. + + Axis label + - A *dimension scale* must have a rank of 1 and has length ``n``. + Unit in which the coordinate values are expressed. + See the section :ref:`Design-Units` for more information. - - - Axis label + ``0|false``: single value, @@ -302,37 +267,26 @@ 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. + Do not use the :ref:`axes </NXdata@axes-attribute>` attribute with the ``axis`` attribute. + The :ref:`axes </NXdata@axes-attribute>` attribute is now preferred. - - - "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. - - .. 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. + + 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 freely. 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. + + The maximum rank is ``32`` for compatibility with backend file formats. The rank (``dataRank``) of the ``data`` must satisfy ``1 <= dataRank <= NX_MAXRANK=32``. - At least one ``dim`` must have length ``n``. - Defines the names of the dimension scales + Defines the names of the coordinates (independent axes) for this data set as a colon-delimited array. - NOTE: The ``axes`` attribute is the preferred + NOTE: The :ref:`axes </NXdata@axes-attribute>` attribute is the preferred method of designating a link. - Do not use the ``axes`` attribute with the ``axis`` attribute. + Do not use the :ref:`axes </NXdata@axes-attribute>` attribute with the ``axis`` attribute. data label + + + "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. + + Standard deviations of data values - @@ -370,13 +334,13 @@ - The ``errors`` must have - the same rank (``dataRank``) - as the ``data``. - At least one ``dim`` must have length "n". + The ``errors`` must have the same rank (``dataRank``) + as the ``data``. + + The elements in data are usually float values really. For @@ -391,15 +355,22 @@ An optional offset to apply to the values in data. + + Title for the plot. + + This is an array holding the values to use for the x-axis of - data. The units must be appropriate for the measurement. + data. The units must be appropriate for the measurement. + + This is a special case of a :ref:`AXISNAME field </NXdata/AXISNAME-field>` + kept for backward compatiblity. @@ -408,7 +379,10 @@ This is an array holding the values to use for the y-axis of - data. The units must be appropriate for the measurement. + data. The units must be appropriate for the measurement. + + This is a special case of a :ref:`AXISNAME field </NXdata/AXISNAME-field>` + kept for backward compatiblity. @@ -417,7 +391,10 @@ This is an array holding the values to use for the z-axis of - data. The units must be appropriate for the measurement. + data. The units must be appropriate for the measurement. + + This is a special case of a :ref:`AXISNAME field </NXdata/AXISNAME-field>` + kept for backward compatiblity. diff --git a/base_classes/NXlog.nxdl.xml b/base_classes/NXlog.nxdl.xml index 813d0e918d..2a71845650 100644 --- a/base_classes/NXlog.nxdl.xml +++ b/base_classes/NXlog.nxdl.xml @@ -49,8 +49,8 @@ can be used to accomodate non standard clocks. - This method of storing logged data helps to distinguish - instances in which a variable is a dimension scale of the data, in which case it is stored + This method of storing logged data helps to distinguish instances in which a variable contains signal or + coordinate values of plottable data, in which case it is stored in an :ref:`NXdata` group, and instances in which it is logged during the run, when it should be stored in an :ref:`NXlog` group. diff --git a/base_classes/NXmonitor.nxdl.xml b/base_classes/NXmonitor.nxdl.xml index fce17418f2..e6444a28e9 100644 --- a/base_classes/NXmonitor.nxdl.xml +++ b/base_classes/NXmonitor.nxdl.xml @@ -30,7 +30,7 @@ A monitor of incident beam data. It is similar to the :ref:`NXdata` groups containing - monitor data and its associated dimension scale, e.g. time_of_flight or + monitor data and its associated coordinates, e.g. time_of_flight or wavelength in pulsed neutron instruments. However, it may also include integrals, or scalar monitor counts, which are often used in both in both pulsed and steady-state instrumentation.