Merge pull request #685 from nexusformat/errors_uncertainties_634

integrate NIAC decision on errors & uncertainties

base_classes/NXdata.nxdl.xml

@@ -266,11 +266,16 @@
 	</field>
 	<field name="VARIABLE_errors" type="NX_NUMBER" nameType="any">
 		<doc>
-			Errors (uncertainties) associated with axis ``VARIABLE``.
+			"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.
+			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 dataset named ``VARIABLE``.  This pattern also 
+			applies to other relationships such as ``VARIABLE_resolutions``
+			to connect additional data with a certain dataset. 
 		</doc>
 		<dimensions rank="1">
 			<doc>
@@ -321,29 +326,10 @@
 				Do not use the ``axes`` attribute with the ``axis`` attribute.
 			</doc>
 		</attribute>
-		<attribute name="uncertainties">
-			<!-- 
-				see http://wiki.nexusformat.org/2014_axes_and_uncertainties
-				not accepted at NIAC2014
-				"NIAC will see a proposal when experience has been gained with all variations."
-			-->
-			<doc>
-				Specify the name (or names) of the uncertainties (errors) 
-				of the dependent axes as plottable data.
-				NOTE: The ``uncertainties`` attribute uses the same syntax
-				as the ``axes`` attribute, a string or an array of strings 
-				for multiple uncertainties.
-
-				Examples::
-
-					@uncertainties="data_errors"
-
-					@uncertainties="Idev"
-
-					@uncertainties=["dQw", "dQl"]
-
-			</doc>
-		</attribute>
+		<!--
+			NIAC2018 voted to use VARIABLE_errors, not @uncertainties
+			https://github.com/nexusformat/definitions/issues/634
+		-->
 		<attribute name="long_name">
 			<doc>data label</doc>
 		</attribute>

manual/source/datarules.rst

@@ -80,6 +80,7 @@ described by the following :index:`rules <rules; naming>`:
    
    will be flagged as a warning during data file validation.
 
+.. _use-underscore:
 
 .. rubric:: Use of underscore in descriptive names
 
@@ -105,6 +106,7 @@ adequately documented.
 	    Terms with other names are permitted but might not be recognized by standard software. 
 	    Rather than persist in using names not specified in the standard, please suggest additions to the :ref:`NIAC`.
 
+.. _target_value:
 
 The data stored in NeXus fields must be readback values. This means values as read from the detector, other hardware etc. 
 There are occasions where it is sensible to store the target value the variable was supposed to have. In this case the target 
@@ -119,6 +121,28 @@ value is stored with a name built by appending _set to the normal NeXus field na
 The temperature field will hold the readback from the cryostat/furnace/whatever. The field temperature_set will hold 
 the target value for the temperature as set by the experiment control software. 
 
+.. _reserved_suffixes:
+
+.. rubric:: Reserved field name suffixes
+
+When naming a field (or dataset), NeXus has reserved certain suffixes to the names
+so that a specific meaning may be attached.  Consider a field named ``DATASET``,
+the following table lists the suffixes reserved by NeXus.
+
+=================  =========================  =================================
+suffix             reference                  meaning
+=================  =========================  =================================
+`_end`             :ref:`NXtransformations`   end points of the motions that start with ``DATASET``
+`_errors`          :ref:`NXdata`              uncertainties (a.k.a., errors)
+`_increment_set`   :ref:`NXtransformations`   intended average range through which the corresponding axis moves during the exposure of a frame
+`_indices`         :ref:`NXdata`              Integer array that defines the indices of the signal field which need to be used in the ``DATASET`` in order to reference the corresponding axis value
+`_set`             :ref:`target_value`        Target value of ``DATASET``
+=================  =========================  =================================
+
+.. Note that the following line might be added to the above table pending discussion:
+
+   `_axes`            :ref:`NXdata`              String array naming data fields for each axis of ``DATASET``
+
 
 .. _Design-Variants:
 
@@ -153,6 +177,28 @@ variants will be rarely used and NXprocess groups with the results of
 data reduction will be written instead. 
 
 
+.. _Design-Uncertainties:
+
+Uncertainties or Errors
+########################
+
+It is desirable to store experimental errors together with the data. NeXus supports this through 
+a convention: uncertainties or experimental errors on data are stored in a separate field which has a name 
+consisting of the original name of the data with _errors appended to it. These uncertainties fields have the 
+sampe shape as the original data field.
+
+An example, from NXdetector:
+
+.. code-block:: text
+               data
+               data_errors
+               beam_center_x
+               beam_center_x_errors
+
+Where data errors would contain the erros on data, and beam_center_x_errors the error on 
+the beam center for x. 
+
+
 .. _Design-ArrayStorageOrder:
 
 NeXus Array Storage Order

utils/dev_create_release_notes.py

@@ -5,4 +5,4 @@
 '''
 
 from create_release_notes import main
-main("v3.3", head="master", milestone="NXDL 2018.5")
+main("NXDL 2018.5", head="master", milestone="NXDL 2020.1")