From 5fc09fbe9c8e908f12269177876217d113a1aa09 Mon Sep 17 00:00:00 2001 From: Mark Koennecke Date: Thu, 23 May 2019 14:46:17 +0200 Subject: [PATCH 1/2] Added documentation for variants to datarules.rst Refs #645 --- manual/source/datarules.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/manual/source/datarules.rst b/manual/source/datarules.rst index 4a2e54c3c4..787452c7d2 100644 --- a/manual/source/datarules.rst +++ b/manual/source/datarules.rst @@ -119,6 +119,39 @@ 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. + +.. _Design-Variants: + + +Variants +######### + +Sometimes it is necessary to store alternate values of a NeXus dataset +in a NeXus file. A common example may be the beam center of which a +value is available at data acquisition. But later on, as part of the +data reduction, a better beam center is calculated. In order to store +this the original field can have a variant attribute which points to +the dataset containing the improved value. If even better values +become available, this dataset can also have a variant attribute +pointing to the next better value for the dataset. A reader the can +follow the variant chain and locate the desired variant. + +A little example is in order to illustrate the scheme: + +.. code-block:: text + + beam_center_x + @variant=beam_center_x_refined + beam_center_x_refined + @variant=beam_center_x_super_refined + beam_center_x_super_refined + +NeXus borrowed this scheme from CIF. In this way all the different +variants of a dataset can be preserved. The expectation is that +variants will be rarely used and NXprocess groups with the results of +data reduction will be written instead. + + .. _Design-ArrayStorageOrder: NeXus Array Storage Order From 2c89d95adbaa6aa7aa346e9ab4b5818f3b5fc435 Mon Sep 17 00:00:00 2001 From: Ben Watts Date: Tue, 21 Jan 2020 23:17:59 +0100 Subject: [PATCH 2/2] Corrected text for Variants section Corrected text to match match comment https://github.com/nexusformat/definitions/issues/645#issuecomment-461820912 in issue #645 --- manual/source/datarules.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/manual/source/datarules.rst b/manual/source/datarules.rst index 787452c7d2..79ba43747b 100644 --- a/manual/source/datarules.rst +++ b/manual/source/datarules.rst @@ -127,14 +127,15 @@ Variants ######### Sometimes it is necessary to store alternate values of a NeXus dataset -in a NeXus file. A common example may be the beam center of which a -value is available at data acquisition. But later on, as part of the -data reduction, a better beam center is calculated. In order to store -this the original field can have a variant attribute which points to -the dataset containing the improved value. If even better values -become available, this dataset can also have a variant attribute -pointing to the next better value for the dataset. A reader the can -follow the variant chain and locate the desired variant. +in a NeXus file. A common example may be the beam center of which a +rough value is available at data acquisition. But later on, a better beam +center is calculated as part of the data reduction. In order to store +this without losing the historical information, the original field can be given a variant attribute that points to +a new dataset containing the obsolete value. If even better values +become available, further datasets can be inserted into the chain of variant attributes +pointing to the preceeding value for the dataset. A reader can thus +keep the best value in the pre-defined dataset, and also be able to +follow the variant chain and locate older variants. A little example is in order to illustrate the scheme: @@ -143,8 +144,8 @@ A little example is in order to illustrate the scheme: beam_center_x @variant=beam_center_x_refined beam_center_x_refined - @variant=beam_center_x_super_refined - beam_center_x_super_refined + @variant=beam_center_x_initial_guess + beam_center_x_initial_guess NeXus borrowed this scheme from CIF. In this way all the different variants of a dataset can be preserved. The expectation is that