NXdata errors on an axis, signal or auxiliary signal

[woutdenolf]

Closes #1044

Currently NXdata does not allow errors on auxiliary signals.

This PR solves that by

• renaming the VARIABLE field to AXISNAME
• updating the doc of VARIABLE_errors to say it applies to axes, signal or auxiliary signals: this is the actual change, although it is already somewhat support by NeXus as described here.
• deprecate errors in favor of VARIABLE_errors for the signal field

[woutdenolf]

For example an NXdata with 1 axis (energy) and 3 signals (I0, I1 and I2)

test.h5:NXroot
  @NX_class = "NXroot"
  @default = "entry"
  data:NXdata
    @NX_class = "NXdata"
    @auxiliary_signals = ["I1", "I2"]
    @axes = ["energy"]
    @signal = "I0"
    I0:int64[3] = [1, 0, 1]
    I0_errors:float64[3] = [0.1, 0.0, 0.1]  # called "errors" in the current definition
    I1:int64[3] = [1, 0, 1]
    I1_errors:float64[3] = [0.1, 0.0, 0.1] # NOT in current definition
    I2:int64[3] = [1, 0, 1]
    I2_errors:float64[3] = [0.1, 0.0, 0.1] # NOT in current definition
    energy:int64[3] = [1, 5, 2]
    energy_errors:float64[3] = [0.1, 0.4, 0.15]
  entry:NXroot
    @NX_class = "NXroot"
    @default = "data"

import h5py

with h5py.File("test.h5", "w") as f:
    f.attrs["NX_class"] = "NXroot"
    f.attrs["default"] = "entry"

    entry = f.create_group("entry")
    entry.attrs["NX_class"] = "NXroot"
    entry.attrs["default"] = "data"

    data = f.create_group("data")
    data.attrs["NX_class"] = "NXdata"
    data.attrs["axes"] = ["energy"]
    data.attrs["signal"] = "I0"
    data.attrs["auxiliary_signals"] = ["I1", "I2"]

    data["energy"] = [1, 5, 2]
    data["energy_errors"] = [0.1, 0.4, 0.15]

    data["I0"] = [1, 0, 1]
    data["I0_errors"] = [0.1, 0, 0.1]  # called "errors" in the current definition

    data["I1"] = [1, 0, 1]
    data["I1_errors"] = [0.1, 0, 0.1]  # NOT in current definition

    data["I2"] = [1, 0, 1]
    data["I2_errors"] = [0.1, 0, 0.1]  # NOT in current definition

[vasole]

Just to add on it, that is something already found in the documentation at:

https://manual.nexusformat.org/datarules.html?highlight=_errors

but not found when describing NXdata. Here is the information concerning reserved suffixes

Reserved suffixes

When naming a field, 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	NXtransformations	end points of the motions that start with DATASET
_errors	NXdata	uncertainties (a.k.a., errors)
_increment_set	NXtransformations	intended average range through which the corresponding axis moves during the exposure of a frame
_indices	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
_mask		Field containing a signal mask, where 0 means the pixel is not masked. If required, bit masks are defined in NXdetector pixel_mask.
_set	target values	Target value of DATASET
_weights		divide DATASET by these weights [4]

[4]

If DATASET_weights exists and has the same shape as the field, you are supposed to divide DATASET by the weights.

[benajamin]

We seem to have already provided 2 different general strategies for giving errors, as described in https://www.nexusformat.org/NIACDesign.html

Maybe we need to decide between _errors and @uncertainties

[prjemian]

As I recall, this was decide at a previous NIAC to use _errors and deprecate use of @uncertainties. The documentation may be lagging and should be edited to current decision.

[woutdenolf]

I propose to leave _errors vs @uncertainties for another discussion. For example here: #1185

This MR deals specifically with make it clear in NXdata (in its current form, using the _errors convention) how the add errors to signal, axes and auxiliary signals.

[prjemian]

Suggestion to deprecate the errors field since it is superseded by the _errors suffix. (Undefined behavior of both present.)

[mkoennecke]

The link to the NIAC 2018 minutes: https://www.nexusformat.org/NIAC2018Minutes.html

[prjemian]

Looks right to me. Consistent with NIAC2018.

[PeterC-DLS]

Happy with this

[benajamin]

Just to clarify the discussion here, there was a decision at the 2018 NIAC meeting:

The errors field and uncertainties attribute in NXdata to be marked deprecated

Therefore issue #1044 is moot and only a clarification of the documentation is required, which was accomplished by this pull request.