Detector channels

applications/NXmx.nxdl.xml

@@ -764,6 +764,19 @@
                             plate, CMOS, ...
                         </doc>
                     </field>
+
+                    <group name="CHANNELNAME_channel" type="NXdetector_channel">
+                        <doc>
+                            Group containing the description and metadata for a single channel from a multi-channel
+                            detector.
+
+                            Given an :ref:`NXdata` group linked as part of an NXdetector group that has an axis with
+                            named channels (see the example in :ref:`NXdata &lt;/NXdata@default_slice-attribute&gt;`),
+                            the NXdetector will have a series of NXdetector_channel groups, one for each channel,
+                            named CHANNELNAME_channel.
+                        </doc>
+                    </group>
+
                 </group>
                 <group type="NXbeam" minOccurs="1">
                     <attribute name="flux" optional="true">

base_classes/NXdata.nxdl.xml

@@ -115,6 +115,43 @@
 			the axes attribute can be omitted.
 		</doc>
 	</attribute>
+	<attribute name="default_slice">
+		<doc>
+			Which slice of data to show in a plot by default. This is useful especially for
+			datasets with more than 2 dimensions.
+
+			Should be an array of strings of length equal to the number of dimesions
+			in the data, with the following possible values:
+
+			* ".": All the data in this dimension should be included
+			* Integer: Only this slice should be used.
+			* String: Only this slice should be used. Use if AXISNAME_indices is a string
+			  array.
+
+			Example::
+
+			  data:NXdata
+				@signal = "data"
+				@axes = ["image_id", "channel", ".", "."]
+				@image_id_indices = 0
+				@channel_indices = 1
+				@default_slice = [".", "difference", ".", "."]
+				image_id = [1, ..., nP]
+				channel = ["threshold_1", "threshold_2", "difference"]
+				data = uint[nP, nC, i, j]
+
+			Here, a data array with four dimensions, including the number of images
+			(nP) and number of channels (nC), specifies more dimensions than can be
+			visualized with a 2D image viewer for a given image.  Therefore the
+			default_slice attribute specifies that the "difference" channel should be
+			shown by default.
+
+			Alternate version using an integer would look like this (note 2 is a string)::
+
+			    @default_slice = [".", "2", ".", "."]
+
+		</doc>
+	</attribute>
 	<attribute name="AXISNAME_indices" type="NX_INT">
 		<!-- 
 			nxdl.xsd rules do not allow us to show this as a variable name 
@@ -273,14 +310,18 @@
 		but not to describe how the data is to be plotted.
 		(https://www.nexusformat.org/NIAC2018Minutes.html#nxdata-plottype--attribute)
 	</doc>
-	<field name="AXISNAME" type="NX_NUMBER" nameType="any">
+	<field name="AXISNAME" type="NX_CHAR_OR_NUMBER" nameType="any">
 		<doc>
-	 		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.
-	 	</doc>
+			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.
+
+			Most dimensions scales will be sequences of numbers but if an
+			axis is better represented using names, such as channel names,
+			an array of NX_CHAR can be provided.
+		</doc>
 		<dimensions rank="1">
 			<doc>
 				A *dimension scale* must have a rank of 1 and has length ``n``.

base_classes/NXdetector.nxdl.xml

@@ -421,6 +421,18 @@
     </doc>
   </field>
 
+  <group name="CHANNELNAME_channel" type="NXdetector_channel">
+      <doc>
+          Group containing the description and metadata for a single channel from a multi-channel
+          detector.
+
+          Given an :ref:`NXdata` group linked as part of an NXdetector group that has an axis with
+          named channels (see the example in :ref:`NXdata &lt;/NXdata@default_slice-attribute&gt;`),
+          the NXdetector will have a series of NXdetector_channel groups, one for each channel,
+          named CHANNELNAME_channel.
+      </doc>
+  </group>
+
   <group name="efficiency" type="NXdata">
     <doc>Spectral efficiency of detector with respect to e.g. wavelength</doc>
     <attribute name="signal">

base_classes/NXdetector_channel.nxdl.xml

@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl" ?>
+<!--
+# NeXus - Neutron and X-ray Common Data Format
+#
+# Copyright (C) 2008-2022 NeXus International Advisory Committee (NIAC)
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 3 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+# For further information, see http://www.nexusformat.org
+-->
+<definition category="base" extends="NXobject" name="NXdetector_channel"
+            type="group"
+            xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
+            xmlns="http://definition.nexusformat.org/nxdl/3.1"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:xs="http://www.w3.org/2001/XMLSchema"
+            xmlns:ns="http://definition.nexusformat.org/nxdl/@NXDL_RELEASE@"
+            >
+
+  <symbols>
+    <doc>
+      These symbols will be used below to illustrate the coordination of the rank and sizes of datasets and the 
+      preferred ordering of the dimensions. Each of these are optional (so the rank of the datasets 
+      will vary according to the situation) and the general ordering principle is slowest to fastest.
+      The type of each dimension should follow the order of scan points, detector output (e.g. pixels),
+      then time-of-flight (i.e. spectroscopy, spectrometry). Note that the output of a detector is not limited 
+      to single values (0D), lists (1D) and images (2), but three or higher dimensional arrays can be produced 
+      by a detector at each trigger.
+    </doc>
+
+    <symbol name="dataRank"><doc>Rank of the ``data`` field associated with this detector</doc></symbol>
+    <symbol name="nP"><doc>number of scan points</doc></symbol>
+    <symbol name="i"><doc>number of detector pixels in the slowest direction</doc></symbol>
+    <symbol name="j"><doc>number of detector pixels in the second slowest direction</doc></symbol>
+    <symbol name="k"><doc>number of detector pixels in the third slowest direction</doc></symbol>
+  </symbols>
+
+  <doc>
+    Description and metadata for a single channel from a multi-channel detector.
+
+    Given an :ref:`NXdata` group linked as part of an NXdetector group that has an axis with named channels (see the
+    example in :ref:`NXdata &lt;/NXdata@default_slice-attribute&gt;`), the NXdetector will have a series of NXdetector_channel groups, one for each
+    channel, named CHANNELNAME_channel.
+
+    Example, given these axes in the NXdata group::
+
+      @axes = ["image_id", "channel", ".", "."]
+
+    And this list of channels in the NXdata group::
+
+      channel = ["threshold_1", "threshold_2", "difference"]
+
+    The NXdetector group would have three NXdetector_channel groups::
+
+      detector:NXdetector
+        ...
+        threshold_1_channel:NXdetector_channel
+          threshold_energy = float
+          flatfield = float[i, j]
+          pixel_mask = uint[i, j]
+        threshold_2_channel:NXdetector_channel
+          threshold_energy = float
+          flatfield = float[i, j]
+          pixel_mask = uint[i, j]
+        difference_channel:NXdetector_channel
+          threshold_energy = float[2]
+  </doc>
+
+  <field name="threshold_energy" type="NX_FLOAT" units="NX_ENERGY">
+    <doc>Energy at which a photon will be recorded</doc>
+  </field>
+
+  <field name="flatfield_applied" type="NX_BOOLEAN" >
+    <doc>
+      True when the flat field correction has been applied in the
+      electronics, false otherwise.
+    </doc>
+  </field>
+
+  <field name="flatfield" type="NX_NUMBER">
+    <doc>Response of each pixel given a constant input</doc>
+      <dimensions rank="dataRank">
+          <dim index="1" value="i" />
+          <dim index="2" value="j" />
+          <dim index="3" value="k" required="false"/>
+      </dimensions>
+  </field>
+
+  <field name="flatfield_errors" type="NX_FLOAT" >
+    <doc>
+        Errors of the flat field correction data.
+        The form flatfield_error is deprecated.
+    </doc>
+    <dimensions rank="2">
+      <dim index="1" value="i"/>
+      <dim index="2" value="j"/>
+    </dimensions>
+  </field>
+
+  <field name="pixel_mask_applied" type="NX_BOOLEAN" >
+    <doc>
+      True when the pixel mask correction has been applied in the
+      electronics, false otherwise.
+    </doc>
+  </field>
+
+  <field name="pixel_mask" type="NX_INT">
+    <doc>
+      Custom pixel mask for this channel. May include nP as the first dimension for
+      masks that vary for each scan point.
+    </doc>
+      <dimensions rank="dataRank">
+          <dim index="2" value="i" />
+          <dim index="3" value="j" />
+          <dim index="4" value="k" required="false"/>
+      </dimensions>
+  </field>
+
+  <field name="saturation_value" type="NX_NUMBER">
+    <doc>
+      The value at which the detector goes into saturation.
+      Especially common to CCD detectors, the data
+      is known to be invalid above this value.
+
+      For example, given a saturation_value and an underload_value, the valid
+      pixels are those less than or equal to the saturation_value and greater
+      than or equal to the underload_value.
+
+      The precise type should match the type of the data.
+    </doc>
+  </field>
+
+  <field name="underload_value" type="NX_NUMBER">
+    <doc>
+      The lowest value at which pixels for this detector would be reasonably
+      measured. The data is known to be invalid below this value.
+
+      For example, given a saturation_value and an underload_value, the valid
+      pixels are those less than or equal to the saturation_value and greater
+      than or equal to the underload_value.
+
+      The precise type should match the type of the data.
+    </doc>
+  </field>
+</definition>

nxdlTypes.xsd

@@ -466,6 +466,7 @@
 			nxdl:NX_POSINT
 			nxdl:NX_QUATERNION
 			nxdl:NX_UINT
+			nxdl:NX_CHAR_OR_NUMBER
 			"/>
 	</xs:simpleType>
 
@@ -619,4 +620,14 @@
 		<xs:restriction base="xs:unsignedByte" />
 	</xs:simpleType>
 
+	<xs:simpleType name="NX_CHAR_OR_NUMBER">
+		<xs:annotation>
+			<xs:documentation>Any valid character string or NeXus number representation</xs:documentation>
+		</xs:annotation>
+		<xs:union memberTypes="
+			nxdl:NX_NUMBER
+			nxdl:NX_CHAR
+			" />
+	</xs:simpleType>
+
 </xs:schema>