Rewrite the NXdata scaling_factor and offset fields

nexusformat · Nov 21, 2023 · 650cfc1 · 650cfc1
1 parent a7dda1e
commit 650cfc1
Show file tree

Hide file tree

Showing 2 changed files with 50 additions and 5 deletions.
diff --git a/applications/NXmx.nxdl.xml b/applications/NXmx.nxdl.xml
@@ -142,6 +142,43 @@
                         <dim index="4" value="k" required="false"/>
                     </dimensions>
                 </field>
+
+                <field name="scaling_factor" type="NX_FLOAT" optional="true">
+                    <doc>
+                        An optional scaling factor to apply to the values in data.
+
+                        The elements in data are often stored as integers for efficiency reasons and need
+                        further correction, generating floats.  The two fields scaling_factor and offset
+                        allow linear corrections using the following convention:
+
+                        .. code-block::
+
+                                corrected_data = (data + offset) * scaling_factor
+
+                        This formula will derive the actual physical value, when necessary.
+
+                        Use these fields to specify gain and/or pedestal constants that need to be applied
+                        to the data to correct it to physical values.  For example, if the detector gain
+                        is 10 counts per photon and a constant background of 400 needs to be subtracted
+                        off the pixels, specify scaling_factor as 0.1 and offset as -400 to specifiy the
+                        required conversion from raw counts to pedestal-corrected photons. It is implied
+                        processing software will apply these corrections on-the-fly during processing.
+
+                        The rank of these fields should either be a single value for the full dataset, a
+                        single per-pixel array applied to every image (rank (i, j) or (i, j, k)),
+                        a per-image correction specified with an array whose slowest rank is nP (rank
+                        (np, 1), (np, i, j) or (np, i, j, k)).
+                </doc>
+                </field>
+                <field name="offset" type="NX_FLOAT" optional="true">
+                <doc>
+                        An optional offset to apply to the values in data.
+
+                        See :ref:`scaling_factor` for more information.
+                </doc>
+                </field>
+
+
             </group>
 
             <group type="NXsample">

diff --git a/base_classes/NXdata.nxdl.xml b/base_classes/NXdata.nxdl.xml
@@ -400,16 +400,24 @@
 	<!-- Data vs. plot coordinates -->
 	<field name="scaling_factor" type="NX_FLOAT">
 		<doc>
-			The elements in data are usually float values really. For
-			efficiency reasons these are usually stored as integers
-			after scaling with a scale factor. This value is the scale
-			factor. It is required to get the actual physical value,
-			when necessary.
+			An optional scaling factor to apply to the values in data.
+
+			The elements in data are often stored as integers for efficiency reasons and need
+			further correction, generating floats.  The two fields scaling_factor and offset
+			allow linear corrections using the following convention:
+
+			.. code-block::
+
+				corrected_data = (data + offset) * scaling_factor
+
+			This formula will derive the actual physical value, when necessary.
 		</doc>
 	</field>
 	<field name="offset" type="NX_FLOAT">
 		<doc>
 			An optional offset to apply to the values in data.
+
+			See :ref:`scaling_factor` for more information.
 		</doc>
 	</field>