From 939fb7e4403a41c3fcff9918cd6a9fcba2e03c9d Mon Sep 17 00:00:00 2001 From: woutdenolf Date: Mon, 1 Jul 2024 21:23:57 +0200 Subject: [PATCH] switch order of examples for clarity --- base_classes/NXdata.nxdl.xml | 46 ++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/base_classes/NXdata.nxdl.xml b/base_classes/NXdata.nxdl.xml index 2537c1d3e..773937978 100644 --- a/base_classes/NXdata.nxdl.xml +++ b/base_classes/NXdata.nxdl.xml @@ -142,7 +142,28 @@ Note that `@x_indices` and `@y_indices` attributes can be omitted in this case. However it is strongly encouraged to provide them. - `2. Multi-dimensional axes` + `2. Data dimensions spanned by more than one axis` + + A common case is the need to specify alternative axes for the same dimension + + .. code-block:: + + data:NXdata + @signal = "data" + @axes = ["eta", "q"] + data: float[10,20] + @eta_indices = [0] + @tth_indices = [1] + @q_indices = [1] + eta: float[10] --> coordinates along the first dimension + tth: float[20] --> coordinates along the second dimension (alternative) + q: float[20] --> coordinates along the second dimension (default) + + Note that to recognize `tth` as an axis, `@tth_indices` must be present. Readers that do + not use :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes will + have no way to understand that `tth` is an axis and simple ignore it. + + `3. Multi-dimensional axes` When coordinates do not form a regular grid, multi-dimensional :ref:`AXISNAME </NXdata/AXISNAME-field>` fields can be used. Just remember that the shape of an :ref:`AXISNAME </NXdata/AXISNAME-field>` field must be equal to the shape @@ -171,7 +192,7 @@ This would be invalid since the shape `[10,20]` of `x` is not equal to the shape `[10]` of the spanned data dimensions. Omitting indices for multi-dimensional axes can only be done by repeating the :ref:`AXISNAME </NXdata/AXISNAME-field>` - name in all positions of the :ref:`axes </NXdata@axes-attribute>` attribute which they span. + name in all positions of the :ref:`axes </NXdata@axes-attribute>` attribute which they span. For example .. code-block:: @@ -184,8 +205,6 @@ Note that since ``NXdata`` does not describe how the data is to be plotted or even the dimensionality of the plot, a reader would probably treat this particular example as a 1D signal and plot it as such. - `3. Dimensions spanned by more than one axis` - In the case of multi-dimensional axes, single-dimensional axes are often introduced as default axes to support readers that does not use the :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes or cannot handle multi-dimensional axes. @@ -212,25 +231,6 @@ Technically `@x_set_indices` and `@y_set_indices` can be omitted. However it is strongly encouraged to provide them. - Another common case is the need to specify alternative axes for the same dimension - - .. code-block:: - - data:NXdata - @signal = "data" - @axes = ["eta", "q"] - data: float[10,20] - @eta_indices = [0] - @tth_indices = [1] - @q_indices = [1] - eta: float[10] --> coordinates along the first dimension - tth: float[20] --> coordinates along the second dimension (alternative) - q: float[20] --> coordinates along the second dimension (default) - - Note that to recognize `tth` as an axis, `@tth_indices` must be present. Readers that do - not use :ref:`AXISNAME_indices </NXdata@AXISNAME_indices-attribute>` attributes will - have no way to understand that `tth` is an axis and simple ignore it. - `4. Axes without defaults` Expanding on the 2D scatter example, a stack of 2D scatter data where the stack dimension