-
Notifications
You must be signed in to change notification settings - Fork 57
/
NXdata.nxdl.xml
435 lines (389 loc) · 16 KB
/
NXdata.nxdl.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
<?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 name="NXdata"
type="group"
extends="NXobject"
category="base"
ignoreExtraFields="true"
ignoreExtraAttributes="true"
xmlns="http://definition.nexusformat.org/nxdl/3.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
>
<!--
The ignoreExtra* attributes are used in the definition to
avoid warning messages that would be generated from unexpected fields or attributes.
Since common use of NXdata indicates field names of any value, _many_
instances of this class would generate a warning message during validation
without this attribute being set to "true".
-->
<symbols>
<doc>These symbols will be used below to coordinate datasets with the same shape.</doc>
<symbol name="dataRank"><doc>rank of the ``data`` field</doc></symbol>
<symbol name="n"><doc>length of the ``variable`` field</doc></symbol>
<symbol name="nx"><doc>length of the ``x`` field</doc></symbol>
<symbol name="ny"><doc>length of the ``y`` field</doc></symbol>
<symbol name="nz"><doc>length of the ``z`` field</doc></symbol>
</symbols>
<attribute name="auxiliary_signals">
<doc>
.. index:: plotting
Array of strings holding the names of additional signals to
be plotted with the default signal (specified by the
``signal`` attribute). Each auxiliary signal needs to be of
the same shape as the default signal.
.. NIAC2018:
https://www.nexusformat.org/NIAC2018Minutes.html
</doc>
</attribute>
<attribute name="signal">
<doc>
.. index:: plotting
Declares which dataset is the default.
The value is the name of the dataset to be plotted.
A field of this name *must* exist (either as dataset
or as a link to a dataset).
It is recommended (as of NIAC2014) to use this attribute
rather than adding a signal attribute to the dataset.
See https://www.nexusformat.org/2014_How_to_find_default_data.html
for a summary of the discussion.
</doc>
</attribute>
<attribute name="axes">
<doc>
.. index:: plotting
String array that defines the independent data fields used in
the default plot for all of the dimensions of the *signal* field
(the *signal* field is the field in this group that is named by
the ``signal`` attribute of this group).
One entry is provided for every dimension in the *signal* field.
The field(s) named as values (known as "axes") of this attribute
*must* exist. An axis slice is specified using a field named
``AXISNAME_indices`` as described below (where the text shown here
as ``AXISNAME`` is to be replaced by the actual field name).
When no default axis is available for a particular dimension
of the plottable data, use a "." in that position.
Such as::
@axes=["time", ".", "."]
Since there are three items in the list, the the *signal* field
must must be a three-dimensional array (rank=3). The first dimension
is described by the values of a one-dimensional array named ``time``
while the other two dimensions have no fields to be used as dimension scales.
See examples provided on the NeXus wiki:
https://www.nexusformat.org/2014_axes_and_uncertainties.html
If there are no axes at all (such as with a stack of images),
the axes attribute can be omitted.
</doc>
</attribute>
<attribute name="AXISNAME_indices">
<!--
nxdl.xsd rules do not allow us to show this as a variable name
- we'll use ALL CAPS (see #562)
-->
<!-- AXISNAME_indices documentation copied from datarules.rst -->
<doc>
Each ``AXISNAME_indices`` attribute indicates the dependency
relationship of the ``AXISNAME`` field (where ``AXISNAME``
is the name of a field that exists in this ``NXdata`` group)
with one or more dimensions of the plottable data.
Integer array that defines the indices of the *signal* field
(that field will be a multidimensional array)
which need to be used in the *AXISNAME* dataset in
order to reference the corresponding axis value.
The first index of an array is ``0`` (zero).
Here, *AXISNAME* is to be replaced by the name of each
field described in the ``axes`` attribute.
An example with 2-D data, :math:`d(t,P)`, will illustrate::
data_2d:NXdata
@signal="data"
@axes=["time", "pressure"]
@time_indices=0
@pressure_indices=1
data: float[1000,20]
time: float[1000]
pressure: float[20]
This attribute is to be provided in all situations.
However, if the indices attributes are missing
(such as for data files written before this specification),
file readers are encouraged to make their best efforts
to plot the data.
Thus the implementation of the
``AXISNAME_indices`` attribute is based on the model of
"strict writer, liberal reader".
.. note:: Attributes potentially containing multiple values
(axes and _indices) are to be written as string or integer arrays,
to avoid string parsing in reading applications.
</doc>
</attribute>
<doc>
:ref:`NXdata` describes the plottable data and related dimension scales.
.. index:: plotting
It is mandatory that there is at least one :ref:`NXdata` group
in each :ref:`NXentry` group.
Note that the ``variable`` and ``data``
can be defined with different names.
The ``signal`` and ``axes`` attributes of the
``data`` group define which items
are plottable data and which are *dimension scales*, respectively.
:ref:`NXdata` is used to implement one of the basic motivations in NeXus,
to provide a default plot for the data of this :ref:`NXentry`. The actual data
might be stored in another group and (hard) linked to the :ref:`NXdata` group.
* Each :ref:`NXdata` group will define only one data set
containing plottable data, dimension scales, and
possibly associated standard deviations.
Other data sets may be present in the group.
* The plottable data may be of arbitrary rank up to a maximum
of ``NX_MAXRANK=32``.
* The plottable data will be named as the value of
the group ``signal`` attribute, such as::
data:NXdata
@signal = "counts"
@axes = "mr"
@mr_indices = 0
counts: float[100] --> the default dependent data
mr: float[100] --> the default independent data
The field named in the ``signal`` attribute **must** exist, either
directly as a dataset or defined through a link.
* The group ``axes`` attribute will name the
*dimension scale* associated with the plottable data.
If available, the standard deviations of the data are to be
stored in a data set of the same rank and dimensions, with the name ``errors``.
* For each data dimension, there should be a one-dimensional array
of the same length.
* These one-dimensional arrays are the *dimension scales* of the
data, *i.e*. the values of the independent variables at which the data
is measured, such as scattering angle or energy transfer.
.. index:: link
.. index:: axes (attribute)
The preferred method to associate each data dimension with
its respective dimension scale is to specify the field name
of each dimension scale in the group ``axes`` attribute as a string list.
Here is an example for a 2-D data set *data* plotted
against *time*, and *pressure*. (An additional *temperature* data set
is provided and could be selected as an alternate for the *pressure* axis.)::
data_2d:NXdata
@signal="data"
@axes=["time", "pressure"]
@pressure_indices=1
@temperature_indices=1
@time_indices=0
data: float[1000,20]
pressure: float[20]
temperature: float[20]
time: float[1000]
.. rubric:: Old methods to identify the plottable data
There are two older methods of associating
each data dimension to its respective dimension scale.
Both are now out of date and
should not be used when writing new data files.
However, client software should expect to see data files
written with any of these methods.
* One method uses the ``axes``
attribute to specify the names of each *dimension scale*.
* The oldest method uses the ``axis`` attribute on each
*dimension scale* to identify
with an integer the axis whose value is the number of the dimension.
.. index: !plot; axis label
plot, axis units
units
dimension scale
Each axis of the plot may be labeled with information from the
dimension scale for that axis. The optional ``@long_name`` attribute
is provided as the axis label default. If ``@long_name`` is not
defined, then use the name of the dimension scale. A ``@units`` attribute,
if available, may be added to the axis label for further description.
See the section :ref:`Design-Units` for more information.
.. index: !plot; axis title
The optional ``title`` field, if available, provides a suggested
title for the plot. If no ``title`` field is found in the :ref:`NXdata`
group, look for a ``title`` field in the parent :ref:`NXentry` group,
with a fallback to displaying the path to the :ref:`NXdata` group.
NeXus is about how to find and annotate the data to be plotted
but not to describe how the data is to be plotted.
(https://www.nexusformat.org/NIAC2018Minutes.html#nxdata-plottype--attribute)
</doc>
<field name="VARIABLE" type="NX_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>
<dimensions rank="1">
<doc>
A *dimension scale* must have a rank of 1 and has length ``n``.
</doc>
<dim index="1" value="n"/>
</dimensions>
<attribute name="long_name"><doc>Axis label</doc></attribute>
<attribute name="distribution" type="NX_BOOLEAN">
<doc>
``0|false``: single value,
``1|true``: multiple values
</doc>
</attribute>
<attribute name="first_good" type="NX_INT"><doc>Index of first good value</doc></attribute>
<attribute name="last_good" type="NX_INT"><doc>Index of last good value</doc></attribute>
<attribute name="axis" type="NX_POSINT"
deprecated="Use the group ``axes`` attribute (NIAC2014)">
<doc>
Index (positive integer) identifying this specific set of numbers.
N.B. The ``axis`` attribute is the old way of designating a link.
Do not use the ``axes`` attribute with the ``axis`` attribute.
The ``axes`` *group* attribute is now preferred.
</doc>
</attribute>
</field>
<field name="VARIABLE_errors" type="NX_NUMBER" nameType="any">
<doc>
"Errors" (actually *uncertainties*) associated with axis ``VARIABLE``.
Client is responsible for defining the dimensions of the data.
The name of this field may be changed to fit the circumstances
but is matched with the *VARIABLE* field with ``_errors`` appended.
This pattern of using ``VARIABLE_errors`` can be used
throughout a NeXus data file to associate uncertainties
with a dataset named ``VARIABLE``. This pattern also
applies to other relationships such as ``VARIABLE_resolutions``
to connect additional data with a certain dataset.
</doc>
<dimensions rank="1">
<doc>
A dimension scale must have a rank of 1 and has length ``n``,
same as ``variable``.
</doc>
<dim index="1" value="n"/>
</dimensions>
</field>
<field name="DATA" type="NX_NUMBER" nameType="any">
<doc>
.. index:: plotting
This field contains the data values to be used as the
NeXus *plottable 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>
<dimensions rank="dataRank">
<doc>
The rank (``dataRank``) of the ``data`` must satisfy
``1 <= dataRank <= NX_MAXRANK=32``.
At least one ``dim`` must have length ``n``.
</doc>
<dim index="0" value="n"><!-- index="0": cannot know to which dimension this applies a priori --></dim>
</dimensions>
<attribute name="signal" type="NX_POSINT"
deprecated="Use the group ``signal`` attribute (NIAC2014)">
<doc>
.. index:: plotting
Plottable (independent) axis, indicate index number.
Only one field in a :ref:`NXdata` group may have the
``signal=1`` attribute.
Do not use the ``signal`` attribute with the ``axis`` attribute.
</doc>
</attribute>
<attribute name="axes"
deprecated="Use the group ``axes`` attribute (NIAC2014)">
<doc>
Defines the names of the dimension scales
(independent axes) for this data set
as a colon-delimited array.
NOTE: The ``axes`` attribute is the preferred
method of designating a link.
Do not use the ``axes`` attribute with the ``axis`` attribute.
</doc>
</attribute>
<!--
NIAC2018 voted to use VARIABLE_errors, not @uncertainties
https://github.com/nexusformat/definitions/issues/634
-->
<attribute name="long_name">
<doc>data label</doc>
</attribute>
</field>
<field name="errors" type="NX_NUMBER">
<doc>
Standard deviations of data values -
the data array is identified by the group attribute ``signal``.
The ``errors`` array must have the same dimensions as ``data``.
Client is responsible for defining the dimensions of the data.
</doc>
<dimensions rank="dataRank">
<doc>
The ``errors`` must have
the same rank (``dataRank``)
as the ``data``.
At least one ``dim`` must have length "n".
</doc>
<dim index="0" value="n"><!-- index="0": cannot know to which dimension this applies a priori --></dim>
</dimensions>
</field>
<field name="scaling_factor" type="NX_FLOAT">
<doc>
The elements in data are usually float values really. For
efficiency reasons these are usually stored as integers
after scaling with a scale factor. This value is the scale
factor. It is required to get the actual physical value,
when necessary.
</doc>
</field>
<field name="offset" type="NX_FLOAT">
<doc>
An optional offset to apply to the values in data.
</doc>
</field>
<field name="title">
<doc>
Title for the plot.
</doc>
</field>
<field name="x" type="NX_FLOAT" units="NX_ANY">
<doc>
This is an array holding the values to use for the x-axis of
data. The units must be appropriate for the measurement.
</doc>
<dimensions rank="1">
<dim index="1" value="nx" />
</dimensions>
</field>
<field name="y" type="NX_FLOAT" units="NX_ANY">
<doc>
This is an array holding the values to use for the y-axis of
data. The units must be appropriate for the measurement.
</doc>
<dimensions rank="1">
<dim index="1" value="ny" />
</dimensions>
</field>
<field name="z" type="NX_FLOAT" units="NX_ANY">
<doc>
This is an array holding the values to use for the z-axis of
data. The units must be appropriate for the measurement.
</doc>
<dimensions rank="1">
<dim index="1" value="nz" />
</dimensions>
</field>
</definition>