From 41b754c26089b07ea91f50c1276d2c333c7d8c74 Mon Sep 17 00:00:00 2001
From: "Aaron S. Brewster" <asbrewster@lbl.gov>
Date: Wed, 20 Dec 2023 09:38:20 -0800
Subject: [PATCH] Allow dimensions in NXdata to be lists of strings (#1246)

* Add new datatype, the union of NX_CHAR and NX_NUMBER
* Change AXISNAME field of NXdata to allow character values
* Add NXdata attribute default_slice: which slice of data to show in a plot by default. This is useful especially for datasets with more than 2 dimensions.

Co-authored-by: Sophie Hotz <sophie.hotz@dectris.com>
---
 base_classes/NXdata.nxdl.xml | 50 +++++++++++++++++++++++++++++++++++-
 nxdlTypes.xsd                | 11 ++++++++
 2 files changed, 60 insertions(+), 1 deletion(-)

diff --git a/base_classes/NXdata.nxdl.xml b/base_classes/NXdata.nxdl.xml
index 2c9d69620..3ed18ff4c 100644
--- a/base_classes/NXdata.nxdl.xml
+++ b/base_classes/NXdata.nxdl.xml
@@ -264,6 +264,51 @@
 			    https://www.nexusformat.org/NIAC2018Minutes.html
 		</doc>
 	</attribute>
+	<attribute name="default_slice" type="NX_CHAR_OR_NUMBER">
+		<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 length equal to the number of dimensions
+			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`` 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)::
+
+			  data:NXdata
+				@signal = "data"
+				@axes = ["image_id", "channel", ".", "."]
+				@image_id_indices = 0
+				@channel_indices = 1
+				@default_slice = [".", "2", ".", "."]
+				image_id = [1, ..., nP]
+				channel = ["threshold_1", "threshold_2", "difference"]
+				data = uint[nP, nC, i, j]
+
+		</doc>
+	</attribute>
 	<attribute name="AXISNAME_indices" type="NX_INT">
 		<!-- 
 			nxdl.xsd rules do not allow us to show this as a variable name 
@@ -294,7 +339,7 @@
 	</attribute>
 	
 	<!-- Data and coordinate fields -->
-	<field name="AXISNAME" type="NX_NUMBER" nameType="any">
+	<field name="AXISNAME" type="NX_CHAR_OR_NUMBER" nameType="any">
 		<doc>
 			Coordinate values along one or more :ref:`data &lt;/NXdata/DATA-field&gt;` dimensions. The rank must be equal
 			to the number of dimensions it spans.
@@ -302,6 +347,9 @@
 			As the upper case ``AXISNAME`` indicates, the names of the ``AXISNAME`` fields can be chosen :ref:`freely &lt;validItemName&gt;`.
 			The :ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute can be used to find all datasets in the
 			``NXdata`` that contain coordinate values.
+
+			Most AXISNAME fields 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>
 		<attribute name="long_name"><doc>Axis label</doc></attribute>
 		<attribute name="units">
diff --git a/nxdlTypes.xsd b/nxdlTypes.xsd
index 8811142b9..d6b3d8623 100644
--- a/nxdlTypes.xsd
+++ b/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>