Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix: 1381 change to the axes attribute meaning #1396

Open
wants to merge 20 commits into
base: main
Choose a base branch
from
Open

Fix: 1381 change to the axes attribute meaning #1396

Show file tree
Hide file tree
Changes from 17 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
b1ad2e6
sometimes referred to as -> also referred to as
woutdenolf Jun 30, 2024
26315aa
NXdata@axes rectification: contains the default axes, not all axes
woutdenolf Jun 30, 2024
d19ff47
clarify what "equal shape" means
woutdenolf Jul 1, 2024
7844bda
rephrase the fact that a list of axis names is not provided by NXdata…
woutdenolf Jul 1, 2024
d85f56c
clarify that one dimension is covered by more than on axis
woutdenolf Jul 1, 2024
61343dd
capitals DATA in analogy to AXISNAME
woutdenolf Jul 1, 2024
939fb7e
switch order of examples for clarity
woutdenolf Jul 1, 2024
ecd53dc
use "spanned" instead of "covered"
woutdenolf Jul 1, 2024
69e53c9
each dimension can only have one default axis
woutdenolf Jul 17, 2024
9a78a11
remove justification for the complex axes definition
woutdenolf Jul 17, 2024
1c61a09
reword
woutdenolf Jul 17, 2024
6a014b5
reword
woutdenolf Jul 17, 2024
115e631
change quotes
woutdenolf Jul 17, 2024
c8e5d6c
change quotes
woutdenolf Jul 17, 2024
27cfde3
reword
woutdenolf Jul 17, 2024
37306ef
express length(axes) == rank(data) in NXDL
woutdenolf Aug 15, 2024
e37a676
NIAC suggestions: start with simple example at the top, histogram axi…
woutdenolf Aug 15, 2024
0bf8672
review
woutdenolf Aug 20, 2024
6b23f02
#edges = #data_points + 1
woutdenolf Aug 20, 2024
c27e2d3
WIP
woutdenolf Sep 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
292 changes: 154 additions & 138 deletions base_classes/NXdata.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,8 @@

<doc>
The :ref:`NXdata` class is designed to encapsulate all the information required for a set of data to be plotted.
NXdata groups contain plottable data (sometimes referred to as *signals* or *dependent variables*) and their
associated axis coordinates (sometimes referred to as *axes* or *independent variables*).
NXdata groups contain plottable data (also referred to as *signals* or *dependent variables*) and their
associated axis coordinates (also referred to as *axes* or *independent variables*).

The actual names of the :ref:`DATA &lt;/NXdata/DATA-field&gt;` and :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` fields
can be chosen :ref:`freely &lt;validItemName&gt;`, as indicated by the upper case (this is a common convention in all NeXus classes).
Expand All @@ -60,176 +60,181 @@
does not describe how the data is to be plotted or even the dimensionality of the plot.
https://www.nexusformat.org/NIAC2018Minutes.html#nxdata-plottype--attribute

**Usage:**

.. admonition:: Plot data versus x axis

.. code-block::

data:NXdata
@signal = "data"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@signal is optional and if missing, we use data so maybe simplest example should omit it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not know this. Not specified in the definition. I'll add it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess when @axes is missing, we use [".", ".", ...] (as many dots as rank)?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If @signal is missing, there is no rule that says "data" is required as a field name. In this case and multiple fields, selection of the signal field for the default plot is not guaranteed.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought NXdata evolved from a fixed signal field (usually called data, see e.g.

definitions/base_classes/NXdata.nxdl.xml

Line 152 in 04bfe4c

<field name="data" type="NX_NUMBER">
) with an (optional?) attribute @signal=1 so to be backwardly compatible, a modern parser could assume the group attribute signal if missing is "data".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that @prjemian is correct. I just scanned through the minutes of all the NIAC meetings, and I can't find any reference to a default name for the signal. I believe that the current (non-deprecated) method of defining signals and axes requires both signal and axes attributes to be defined at group level.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was found that assigning these links to fields would break when the fields were linked (local or external) into other groups. Such field attributes could produce a group with multiple field @signal attributes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we need to make these attributes required then.

Copy link
Contributor

@prjemian prjemian Aug 20, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could bring that up again for a NIAC vote. Should not make it required until then, since NIAC voted the other way.

Consider a simple use case (for not having this attribute). User wants to save a 2-D image, only the 2-D image. NeXus file consists of /entry:NXentry/data:NXdata/image where image is the 2-D image. We've gotten strong pushback on requiring @signal in this use case.

@axes = ["x"]
data: float[100]
x: float[100]

More complex cases are supported

* histogram data: ``x`` has one more value than ``data``.
* alternative axes: instead of a single ``x`` axis you can have several axes, one of which being the default.
* signals with more than one dimension: ``data`` could be 2D with axes ``x`` and ``y`` along each dimension.
* axes with more than one dimension: ``data`` could be 2D with axes ``x`` and ``y`` also being 2D, providing a
unique ``[x, y]`` coordinate for each ``data`` point.
woutdenolf marked this conversation as resolved.
Show resolved Hide resolved

**Signals:**

.. index:: plotting


.. admonition:: Defined by

* :ref:`DATA &lt;/NXdata/DATA-field&gt;` fields
* the :ref:`signal &lt;/NXdata@signal-attribute&gt;` attribute
* the :ref:`auxiliary_signals&lt;/NXdata@auxiliary_signals-attribute&gt;` attribute

The :ref:`DATA &lt;/NXdata/DATA-field&gt;` fields contain the signal values to be plotted. The name of the field
to be used as the *default plot signal* is provided by the :ref:`signal &lt;/NXdata@signal-attribute&gt;` attribute.
The names of the fields to be used as *secondary plot signals* are provided by the
:ref:`auxiliary_signals&lt;/NXdata@auxiliary_signals-attribute&gt;` attribute.

An example with three signals, one of which being the default
.. admonition:: An example with three signals, one of which being the default

.. code-block::
.. code-block::

data:NXdata
@signal = "data1"
@auxiliary_signals = ["data2", "data3"]
data1: float[10,20,30] --> the default signal
data2: float[10,20,30]
data3: float[10,20,30]
data:NXdata
@signal = "data1"
@auxiliary_signals = ["data2", "data3"]
data1: float[10,20,30] --> the default signal
data2: float[10,20,30]
data3: float[10,20,30]

**Axes:**

.. index:: axes (attribute)
.. index:: coordinates

The :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` fields contain the axis coordinates associated with the data values.
The names of all :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` fields are listed in the
:ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute.

`Rank`

:ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` fields are typically one-dimensional arrays, which annotate one of the dimensions.
.. admonition:: Defined by

An example of this would be
* :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` fields
* the :ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute
* :ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;` attributes

.. code-block::
The fields and attributes are defined as follows

data:NXdata
@signal = "data"
@axes = ["x", "y"] --> the order matters
data: float[10,20]
x: float[10] --> coordinates along the first dimension
y: float[20] --> coordinates along the second dimension
1. The :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` fields contain the axis coordinates associated with the signal values.

In this example each data point ``data[i,j]`` has axis coordinates ``[x[i], y[j]]``.
2. The :ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute provides the names of the :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;`
fields to be used as the `default axis` for each dimension of the :ref:`DATA &lt;/NXdata/DATA-field&gt;` fields.

However, the fields can also have a rank greater than 1, in which case the rank of each
:ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` must be equal to the number of data dimensions it spans.
3. The :ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;` attributes describe the :ref:`DATA &lt;/NXdata/DATA-field&gt;`
dimensions spanned by the corresponding :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` fields.

An example of this would be
Additional requirements for a complete definition

.. code-block::
1. The length of the :ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute must be equal to the rank of the :ref:`DATA &lt;/NXdata/DATA-field&gt;`
fields. When a particular dimension has no default axis, the string “.” is used in that position.

data:NXdata
@signal = "data"
@axes = ["x", "y"] --> the order does NOT matter
@x_indices = [0, 1]
@y_indices = [0, 1]
data: float[10,20]
x: float[10,20] --> coordinates along both dimensions
y: float[10,20] --> coordinates along both dimensions
2. The number of values in :ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;` must be equal to the rank of the corresponding
:ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field.

In this example each data point ``data[i,j]`` has axis coordinates ``[x[i,j], y[i,j]]``.
3. When :ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;` is missing for a given
:ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field, the positions of the :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;`
field name in the :ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute are used.

`Dimensions`
4. When :ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;` is the same as the indices of "AXISNAME" in the
:ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute, there is no need to provide
:ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only for 1D axis fields?

Copy link
Contributor Author

@woutdenolf woutdenolf Aug 20, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this applies in general then @axes=["x", "x"] would imply @x_indices=[0,1]. That would be ok when x is 2D.

When x is 1D it would not work. It would violate two requirements

  • The number of values in AXISNAME_indices must be equal to the rank of the corresponding AXISNAME field.
  • The indices of "AXISNAME" in the axes attribute must be a subset of AXISNAME_indices.

So if a 1D x needs to work for @axes=["x", "x"] we need to change those requirements. Edit: for the record I don't think this is needed and if it would be needed, you can use softlinks to have one dataset with two different names.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, a pathological case could be @x_indices=[1,0]

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok I see. So omitting indices can only work unambiguously in 1D cases.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another pathological case would be @x_indices=[0,0]. I'm not sure what this means but technically the definition does not forbid it. So we should say indices cannot contain duplicates?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Eeeeww! That's pathological, and likely a mistake.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah ok, the first example. axes=["x", "x"] would be equivalent to @x_indices=[0,1] no?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Eeeeww! That's pathological, and likely a mistake.

Agreed but technically the definition does not present it as far as I can see, which we should probably fix but not sure how.

Stating that AXISNAME_indices cannot have duplicates would solve it. But it would prohibit the case where you have for example a single 1D x axis of lets say 100 points and you have a 2D signal of 100 x 100 points and you want x to be used for both dimensions. As I said before, you could define x1 and x2 and both can be symlinks to x so effectively x is used for both dimensions even though @axes=["x1", "x2"].

Copy link
Contributor Author

@woutdenolf woutdenolf Sep 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@prjemian Can you modify the code provided in #1396 (comment) to prove that the current specs allow a 1D signal to be used for multiple dimensions without breaking support for multi-dimensional axes?

I don't think it is possible.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure I know how to proceed on this directly. For the variety of different formats considered by canSAS, the discussion resulted in this documentation where the examples are repeated. Those are the places I would examine to test multi-dimensional data.


The data dimensions annotated by an :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field are defined by the
:ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;` attribute. When this attribute is missing,
the position(s) of the :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` string in the
:ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute are used.
5. The indices of "AXISNAME" in the :ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute must be a subset of
:ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;`.

When all :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` fields are one-dimensional, and none of the data dimensions
have more than one axis, the :ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;` attributes
are often omitted. If one of the data dimensions has no :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field,
the string “.” can be used in the corresponding index of the axes list.
6. The shape of an :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field must correspond to the shape of the
:ref:`DATA &lt;/NXdata/DATA-field&gt;` dimensions it spans. This means that for each dimension ``i`` in ``[0, AXISNAME.ndim)``
spanned by an :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field the number of data points along this dimension
``DATA.shape[AXISNAME_indices[i]]`` must be equal to the number of axis values along this dimension ``AXISNAME.shape[i]``
or the number of bin edges ``AXISNAME.shape[i]+1`` in case of histogram data.
woutdenolf marked this conversation as resolved.
Show resolved Hide resolved

An example of this would be
Highlight concequences that follow the definition
woutdenolf marked this conversation as resolved.
Show resolved Hide resolved

.. code-block::
1. An :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field can have more than one dimension and can therefore span
more than one :ref:`DATA &lt;/NXdata/DATA-field&gt;` dimension. Conversely, one :ref:`DATA &lt;/NXdata/DATA-field&gt;` dimension
can be spanned by more than one :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field. The default axis name (if any)
of each dimension can be found in the :ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute.

data:NXdata
@signal = "data"
@axes = ["x", ".", "z"] --> the order matters
data: float[10,20,30]
x: float[10] --> coordinates along the first dimension
z: float[30] --> coordinates along the third dimension
2. A list of all available axes is not provided directly. All strings in the :ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute
(excluding the “.” string) are axis field names. In addition the prefix of an attribute ending with the string "_indices" is also
an axis field name.

When using :ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;` this becomes
.. admonition:: The following example covers all axes features supported

.. code-block::
.. code-block::

data:NXdata
@signal = "data"
@axes = ["x", "z"] --> the order does NOT matter
data: float[10,20,30]
@x_indices = 0
@z_indices = 2
x: float[10] --> coordinates along the first dimension
z: float[30] --> coordinates along the third dimension
data:NXdata
@signal = "data"
@axes = ["x_set", "y_set", "."] --> default axes for all three dimensions
@x_encoder_indices = [0, 1]
@y_encoder_indices = 1 --> or [1]
data: float[10,7,1024]
x_encoder: float[11,7] --> coordinates along the first and second dimensions
y_encoder: float[7] --> coordinates along the second dimension
x_set: float[10] --> coordinates along the first dimension
y_set: float[7] --> coordinates along the second dimension

When providing :ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;` attributes it is recommended
to do it for all axes.
One scientific application that provided such data is 2D scanning X-Ray Fluorescence (XRF)
where the sample is scanned through a focussed X-ray beam in two dimensions and an XRF spectrum
with 1024 channels is recorded at each position. In addition the x motor is scanned
continuously and both motors have an encoder which records the actual motor position as
opposed to the requested or `set` position.

`Non-trivial axes`
.. image:: data/example2D_hist.png
:width: 100%

What follows are two examples where :ref:`AXISNAME_indices &lt;/NXdata@AXISNAME_indices-attribute&gt;` attributes
cannot be omitted.
1. ``@axes`` has three values which corresponds to the ``data`` rank of three

The first is an example where data dimensions have alternative axis coordinates. The NXdata group represents
a stack of images collected at different energies. The ``wavelength`` is an alternative axis of ``energy``
for the last dimension (or vice versa).
2. ``x_set`` and ``y_set`` are the default axes for the first two dimensions while the third
dimension does not have a default axis or any axis for that matter.

.. code-block::
3. ``x_set_indices`` and ``y_set_indices`` are omitted because they would be equal to
the position of ``"x_set"`` and ``"y_set"`` in ``@axes``.

data:NXdata
@signal = "data"
@axes = ["x", "y", "energy", "wavelength"] --> the order does NOT matter
@x_indices = 0
@y_indices = 1
@energy_indices = 2
@wavelength_indices = 2
data: float[10,20,30]
x: float[10] --> coordinates along the first dimension
y: float[20] --> coordinates along the second dimension
energy: float[30] --> coordinates along the third dimension
wavelength: float[30] --> coordinates along the third dimension
4. The first dimension is spanned by two axes ``x_set`` and ``x_encoder``. Since
the x motor is scanned continuously, the encoder records the edge of every bin
on which an XRF spectrum is recorded yielding 11 values instead of 10 along the
first dimension. The ``x_encoder`` spans two dimensions because the actual x edges
are slightly different for every x motion at each y position.

The second is an example with coordinates that span more than one dimension. The NXdata group represents data
from 2D mesh scans performed at multiple energies. Each data point ``data[i,j,k]`` has axis coordinates
``[x[i,j,k], y[i,j,k], energy[k]]``.
5. The second dimension is spanned by two axes ``y_set`` and ``y_encoder``. The axes
have as many values are there are data points along the second dimension. This is
because the y motor moves one step after each scan of the x motor. Since the y
motor does not move while scanning x, there is no need for ``y_encoder`` to span
the first dimension because the value along this dimension remains constant.

.. code-block::
**Uncertainties:**

data:NXdata
@signal = "data"
@axes = ["x", "y", "energy"] --> the order does NOT matter
@x_indices = [0, 1, 2]
@y_indices = [0, 1, 2]
@energy_indices = 2
data: float[10,20,30]
x: float[10,20,30] --> coordinates along all dimensions
y: float[10,20,30] --> coordinates along all dimensions
energy: float[30] --> coordinates along the third dimension
.. admonition:: Defined by

**Uncertainties:**
* :ref:`FIELDNAME_errors &lt;/NXdata/FIELDNAME_errors-field&gt;` fields

Standard deviations on data values as well as coordinates can be provided by
:ref:`FIELDNAME_errors &lt;/NXdata/FIELDNAME_errors-field&gt;` fields where ``FIELDNAME`` is the name of a
:ref:`DATA &lt;/NXdata/DATA-field&gt;` field or an :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field.

An example of uncertainties on the signal, auxiliary signals and axis coordinates

.. code-block::

data:NXdata
@signal = "data1"
@auxiliary_signals = ["data2", "data3"]
@axes = ["x", "z"]
@x_indices = 0
@z_indices = 2
data1: float[10,20,30]
data2: float[10,20,30]
data3: float[10,20,30]
x: float[10]
z: float[30]
data1_errors: float[10,20,30]
data2_errors: float[10,20,30]
data3_errors: float[10,20,30]
x_errors: float[10]
z_errors: float[30]
.. admonition:: An example of uncertainties on the signal, auxiliary signals and axis coordinates

.. code-block::

data:NXdata
@signal = "data1"
@auxiliary_signals = ["data2", "data3"]
@axes = ["x", ".", "z"]
data1: float[10,20,30]
data2: float[10,20,30]
data3: float[10,20,30]
x: float[10]
z: float[30]
data1_errors: float[10,20,30]
data2_errors: float[10,20,30]
data3_errors: float[10,20,30]
x_errors: float[10]
z_errors: float[30]

</doc>

Expand Down Expand Up @@ -316,11 +321,13 @@
-->
<!-- AXISNAME_indices documentation copied from datarules.rst -->
<doc>
The ``AXISNAME_indices`` attribute is a single integer or an array of integers that defines which :ref:`data &lt;/NXdata/DATA-field&gt;`
dimension(s) are spanned by the corresponding axis. The first dimension index is ``0`` (zero).
The ``AXISNAME_indices`` attribute is a single integer or an array of integers that defines which :ref:`DATA &lt;/NXdata/DATA-field&gt;`
dimensions are spanned by the corresponding axis. The first dimension index is ``0`` (zero).

The number of indices must be equal to the rank of the :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field.

When the ``AXISNAME_indices`` attribute is missing for an :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field, its value becomes the index
(or indices) of the :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` name in the :ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute.
When the ``AXISNAME_indices`` attribute is missing for a given :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` field, its value becomes
the index (or indices) of the :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` name in the :ref:`axes &lt;/NXdata@axes-attribute&gt;` attribute.

.. note:: When ``AXISNAME_indices`` contains multiple integers, it must be saved as an actual array
of integers and not a comma separated string.
Expand All @@ -329,26 +336,33 @@
<attribute name="axes">
<doc>
.. index:: plotting

The ``axes`` attribute is a list of strings which are the names of the :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;` fields
that contain the values of the coordinates along the :ref:`data &lt;/NXdata/DATA-field&gt;` dimensions.
to be used as the default axis along every :ref:`DATA &lt;/NXdata/DATA-field&gt;` dimension. As a result the length must
be equal to the rank of the :ref:`DATA &lt;/NXdata/DATA-field&gt;` fields. The string "." can be used for
dimensions without a default axis.

.. note:: When ``axes`` contains multiple strings, it must be saved as an actual array
of strings and not a single comma separated string.
</doc>
<dimensions rank="1">
<dim index="1" value="dataRank"/>
</dimensions>
</attribute>

<!-- Data and coordinate fields -->
<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.

Coordinate values along one or more :ref:`DATA &lt;/NXdata/DATA-field&gt;` dimensions.

The shape of an ``AXISNAME`` field must correspond to the shape of the :ref:`DATA &lt;/NXdata/DATA-field&gt;`
dimensions it spans. This means that for each ``i`` in ``[0, AXISNAME.ndim)`` the number of data points
``DATA.shape[AXISNAME_indices[i]]`` must be equal to the number of coordinates ``AXISNAME.shape[i]`` or the
woutdenolf marked this conversation as resolved.
Show resolved Hide resolved
number of bin edges ``AXISNAME.shape[i]+1`` in case of histogram data.

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,
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>
Expand Down Expand Up @@ -380,7 +394,7 @@
<field name="DATA" type="NX_NUMBER" nameType="any">
<doc>
.. index:: plotting

Data values to be used as the NeXus *plottable data*. As the upper case ``DATA``
indicates, the names of the ``DATA`` fields can be chosen :ref:`freely &lt;validItemName&gt;`. The :ref:`signal attribute &lt;/NXdata@signal-attribute&gt;`
and :ref:`auxiliary_signals attribute&lt;/NXdata@auxiliary_signals-attribute&gt;` can be used to find all datasets in the ``NXdata``
Expand Down Expand Up @@ -424,10 +438,12 @@
<doc>
"Errors" (meaning *uncertainties* or *standard deviations*)
associated with any field named ``FIELDNAME`` in this ``NXdata``
group (e.g. an axis, signal or auxiliary signal).
group. This can be a :ref:`DATA &lt;/NXdata/DATA-field&gt;` field
(signal or auxiliary signal) or a :ref:`AXISNAME &lt;/NXdata/AXISNAME-field&gt;`
field (axis).

The dimensions of the ``FIELDNAME_errors`` field must match
the dimensions of the ``FIELDNAME`` field.
the dimensions of the corresponding ``FIELDNAME`` field.
</doc>
</field>
<field name="errors" type="NX_NUMBER" deprecated="Use ``DATA_errors`` instead (NIAC2018)">
Expand Down
Loading
Loading