Merge pull request #2 from nexusformat/master

Sync HDRMX definitions to nexussormat

NXDL_VERSION

@@ -1 +1,2 @@
-v2020.1HDRMX
+v2020.1
+

applications/NXmx.nxdl.xml

@@ -162,13 +162,13 @@
 					</doc>
 				</group>
 
-				<field name="temperature" units="NX_TEMPERATURE" minOccurs="0" />
+				<field name="temperature" units="NX_TEMPERATURE" type="NX_NUMBER" minOccurs="0" />
 
 			</group>
 
 
 			<group type="NXinstrument">
-				<field name="name" minOccurs="1">
+				<field name="name" type="NX_CHAR" minOccurs="1">
 					<doc>
 						Name of instrument.  Consistency with the controlled 
 						vocabulary beamline naming in http://mmcif.wwpdb.org
@@ -428,7 +428,7 @@
 						</doc>
 					</field>
 
-					<field name="distance_derived" type="NX_BOOLEAN" units="NX_LENGTH" recommended="true">
+					<field name="distance_derived" type="NX_BOOLEAN" recommended="true">
 						<doc>
 							Boolean to indicate if the distance is a derived, rather than
 							a primary observation.  If distance_derived true or is not specified,
@@ -449,7 +449,7 @@
 						</doc>
 					</field>
 
-					<field name="beam_center_derived" type="NX_BOOLEAN" units="NX_LENGTH" optional="true">
+					<field name="beam_center_derived" type="NX_BOOLEAN" optional="true">
 						<doc>
 							Boolean to indicate if the distance is a derived, rather than
 							a primary observation.  If true or not provided, that value of
@@ -507,10 +507,11 @@
 						</doc>
 					</field>
 
-					<field name="flatfield" type="NX_FLOAT" minOccurs="0">
+					<field name="flatfield" type="NX_NUMBER" minOccurs="0">
 						<doc>
 							Flat field correction data.  If provided, it is recommended
-							that is be compressed.
+							that it be compressed.
+
 						</doc>
 						<dimensions rank="dataRank">
 							<dim index="1" value="i" />
@@ -519,7 +520,20 @@
 						</dimensions>
 					</field>
 
-					<field name="flatfield_error" type="NX_FLOAT" minOccurs="0">
+					<field name="flatfield_error" type="NX_NUMBER" minOccurs="0" maxOccurs="0" >
+						<doc>
+							*** Deprecated form.  Use plural form ***
+							Errors of the flat field correction data.  If provided, it is recommended
+							that it be compressed.
+						</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_NUMBER" minOccurs="0">
+
 						<doc>
 							Errors of the flat field correction data.  If provided, it is recommended
 							that it be compressed.
@@ -711,6 +725,12 @@
 							of dimensions **np** by **m** (slow to fast) with the
 							relative weights in incident_wavelength_weight as a 2D
 							array.
+
+							Note, :ref:`variants &lt;Design-Variants&gt;` are a good way
+							to represent several of these use cases in a single dataset,
+							e.g. if a calibrated, single-value wavelength value is
+							available along with the original spectrum from which it
+							was calibrated.
 						</doc>
 					</field>
 
@@ -732,6 +752,11 @@
 						<doc>
 							The wavelength spread FWHM for the corresponding
 							wavelength(s) in incident_wavelength.
+
+							In the case of shot-to-shot variation in the wavelength
+							spread, this is a 2D array of dimension **np** by
+							**m** (slow to fast) of the spreads of the
+							corresponding wavelengths in incident_wavelength.
 						</doc>
 					</field>
 

base_classes/NXdetector.nxdl.xml

@@ -108,11 +108,11 @@
 
   </field>
 
-  <field name="data_error" type="NX_NUMBER" units="NX_ANY">
+  <field name="data_errors" type="NX_NUMBER" units="NX_ANY">
     <doc>
       The best estimate of the uncertainty in the data value. Where
       possible, this should be the standard deviation, which has the same units
-      as the data.
+      as the data. The form data_error is deprecated.
     </doc>
 
     <dimensions rank="4">
@@ -123,6 +123,7 @@
     </dimensions>
   </field>
 
+
   <field name="x_pixel_offset" type="NX_FLOAT" units="NX_LENGTH">
     <doc>
   Offset from the detector center in x-direction.
@@ -572,8 +573,11 @@
       <dim index="2" value="j"/>
     </dimensions>
   </field>
-  <field name="flatfield_error" type="NX_FLOAT" >
-    <doc>Errors of the flat field correction data.</doc>
+  <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"/>

base_classes/NXdetector_module.nxdl.xml

@@ -128,10 +128,10 @@
 	</field>
 	<field name="slow_pixel_direction" type="NX_NUMBER" units="NX_LENGTH">
 		<doc>
-                       Values along the direction of :ref:`slowest varying&lt;Design-ArrayStorageOrder&gt;`  :index:`pixel direction&lt;dimension; slowest varying&gt;`. Each value in this
-                       array is the size of a pixel in the units specified. Alternatively, if only one
-                       value is given, all pixels in this direction have the same value. The direction
-                       itself is given through the vector attribute.
+      Values along the direction of :ref:`slowest varying&lt;Design-ArrayStorageOrder&gt;` :index:`pixel direction&lt;dimension; slowest varying&gt;`. Each value in this
+      array is the size of a pixel in the units specified. Alternatively, if only one
+      value is given, all pixels in this direction have the same value. The direction
+      itself is given through the vector attribute.
 		</doc>
 		<attribute name="transformation_type">
 			<enumeration>

manual/source/datarules.rst

@@ -633,7 +633,7 @@ plottable data is as follows:
       naming the field **in this group** to be used as 
       dimension scales of the default plottable data.  
       The number of values given must be equal to the 
-      *rank* of the *signal* data.  These are the *abcissae*
+      *rank* of the *signal* data.  These are the *abscissae*
       of the plottable *signal* data.
 
       *If* no field is available to provide a dimension scale
@@ -657,7 +657,7 @@ plottable data is as follows:
 
       It is possible there may be more than one ``AXISNAME_indices`` attribute
       with the same value or values.  This indicates the possibilty of using
-      alternate abcissae along this (these) dimension(s).  The
+      alternate abscissae along this (these) dimension(s).  The
       field named in the ``axes`` attribute indicates the intention of
       the data file writer as to which field should be used by default.
 

manual/source/examples/h5py/reader_attributes_trail.py

@@ -0,0 +1,26 @@
+
+import h5py
+
+with h5py.File("prj_test.nexus.hdf5", "r") as nx:
+    # find the default NXentry group
+    nx_entry = nx[nx.attrs["default"]]
+    # find the default NXdata group
+    nx_data = nx_entry[nx_entry.attrs["default"]]
+    # find the signal field
+    signal = nx_data[nx_data.attrs["signal"]]
+    # find the axes field(s)
+    attr_axes = nx_data.attrs["axes"]
+    if isinstance(attr_axes, (set, tuple, list)):
+        #  but check that attr_axes only describes 1-D data
+        if len(attr_axes) == 1:
+            attr_axes = attr_axes[0]
+        else:
+            raise ValueError(f"expected 1-D data but @axes={attr_axes}")
+    axes = nx_data[attr_axes]
+
+    print(f"file: {nx.filename}")
+    print(f"signal: {signal.name}")
+    print(f"axes: {axes.name}")
+    print(f"{axes.name} {signal.name}")
+    for x, y in zip(axes, signal):
+        print(x, y)

manual/source/examples/h5py/reader_attributes_trail.txt

@@ -0,0 +1,35 @@
+file: prj_test.nexus.hdf5
+signal: /entry/mr_scan/I00
+axes: /entry/mr_scan/mr
+/entry/mr_scan/mr /entry/mr_scan/I00
+17.92608 1037
+17.92591 1318
+17.92575 1704
+17.92558 2857
+17.92541 4516
+17.92525 9998
+17.92508 23819
+17.92491 31662
+17.92475 40458
+17.92458 49087
+17.92441 56514
+17.92425 63499
+17.92408 66802
+17.92391 66863
+17.92375 66599
+17.92358 66206
+17.92341 65747
+17.92325 65250
+17.92308 64129
+17.92291 63044
+17.92275 60796
+17.92258 56795
+17.92241 51550
+17.92225 43710
+17.92208 29315
+17.92191 19782
+17.92175 12992
+17.92158 6622
+17.92141 4198
+17.92125 2248
+17.92108 1321

nxdl.xsd

@@ -623,19 +623,23 @@
 				<xs:sequence>
 					<xs:element name="dimensions" type="nx:dimensionsType" minOccurs="0" maxOccurs="1">
 						<xs:annotation>
-							<xs:documentation>dimensions of a data element 
-							in a NeXus file</xs:documentation>
+							<xs:documentation>
+								dimensions of a data element in a NeXus file
+							</xs:documentation>
 						</xs:annotation>
 					</xs:element>
 					<xs:element name="attribute" type="nx:attributeType" minOccurs="0" maxOccurs="unbounded">
 						<xs:annotation>
-							<xs:documentation>attributes to be used with this field</xs:documentation>
+							<xs:documentation>
+								attributes to be used with this field
+							</xs:documentation>
 						</xs:annotation>
 					</xs:element>
 					<xs:element name="enumeration" type="nx:enumerationType" minOccurs="0">
 						<xs:annotation>
-							<xs:documentation>A field can specify which 
-							values are to be used</xs:documentation>
+							<xs:documentation>
+								A field can specify which values are to be used
+							</xs:documentation>
 						</xs:annotation>
 					</xs:element>
 				</xs:sequence>
@@ -700,14 +704,14 @@
 							NOTE: Use of this attribute is discouraged.  It is for legacy support.
 							You should use the axes attribute on the NXdata group instead.
 
-							Presence of the ``axis`` attribute means this field is an abcissa.
+							Presence of the ``axis`` attribute means this field is an abscissa.
 
 							The attribute value is an integer indicating this
 							field as an axis that is part of the data set.
 							The data set is a field with the attribute 
 							``signal=1`` in the same group.
 							The value can range from 1 up to the number of 
-							independent axes (abcissae) in the data set.  
+							independent axes (abscissae) in the data set.  
 
 							A value of ``axis=1``" indicates that this field 
 							contains the data for the first independent axis.  
@@ -733,7 +737,7 @@
 							of this field for plotting (or visualization) as an axis.
 
 							Presence of the ``primary`` attribute means this 
-							field is an abcissa.
+							field is an abscissa.
 						</xs:documentation>
 					</xs:annotation>
 				</xs:attribute>
@@ -818,7 +822,7 @@
 				<xs:attribute name="data_offset" use="optional"  default="1" type="nx:nonNegativeUnbounded">
 					<xs:annotation>
 						<!--
-							note: renamed from "offset" due to comflict with CIF usage.
+							note: renamed from "offset" due to conflict with CIF usage.
 							see: https://github.com/nexusformat/definitions/issues/330#issuecomment-232074420
 							-->
 						<xs:documentation>
@@ -1207,7 +1211,7 @@
 
 	<xs:complexType name="dimensionsType">
 		<!-- 
-			see TRAC ticket #32: https://github.com/nexusformat/definitions/issues/32 
+			see issue #32: https://github.com/nexusformat/definitions/issues/32 
 		-->
 		<xs:annotation>
 			<xs:documentation>

utils/nxdl_desc2rst.py

@@ -191,7 +191,7 @@
 **The** ``xs:string`` **data type**
     The ``xs:string`` data type can contain characters, 
     line feeds, carriage returns, and tab characters.
-    See https://www.w3schools.com/xml/schema_dtypes_string.asp 
+    See https://www.w3schools.com/xml/schema_dtypes_string.asp
     for more details.
 
 **The** ``xs:token`` **data type**
@@ -201,7 +201,7 @@
     The ``xs:token`` data type also contains characters, 
     but the XML processor will remove line feeds, carriage returns, tabs, 
     leading and trailing spaces, and multiple spaces.
-    See https://www.w3schools.com/xml/schema_dtypes_string.asp 
+    See https://www.w3schools.com/xml/schema_dtypes_string.asp
     for more details.
 '''