Skip to content

Commit

Permalink
Merge pull request #1022 from nexusformat/1003-default-attribute-value
Browse files Browse the repository at this point in the history 
improve description of the value of the default attribute
  • Loading branch information
@prjemian
prjemian authored Jun 14, 2022
2 parents 796135b + 06d52e2 commit e045360
Show file tree
Hide file tree
Showing 8 changed files with 444 additions and 421 deletions.
47 changes: 26 additions & 21 deletions base_classes/NXdata.nxdl.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@
-->

<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>
<doc>These symbols will be used below to coordinate fields 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>
Expand All @@ -64,15 +64,17 @@
</attribute>
<attribute name="signal">
<doc>
.. index:: find the default plottable data
.. index:: plotting
.. index:: signal attribute value

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).
Declares which NeXus field is the default.
The value is the name of the NeXus field to be plotted.
(The value :ref:`names &lt;validItemName>` an existing child
of this group. The child group must itself be a NeXus group.)

It is recommended (as of NIAC2014) to use this attribute
rather than adding a signal attribute to the dataset.
rather than adding a signal attribute to the field.
See https://www.nexusformat.org/2014_How_to_find_default_data.html
for a summary of the discussion.
</doc>
Expand Down Expand Up @@ -124,7 +126,7 @@

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
which need to be used in the *AXISNAME* field in
order to reference the corresponding axis value.

The first index of an array is ``0`` (zero).
Expand Down Expand Up @@ -162,10 +164,11 @@

.. 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``
It is strongly recommended that there is at least one :ref:`NXdata`
group in each :ref:`NXentry` group.
Note that the fields named ``VARIABLE`` and ``DATA``
can be defined with different names.
(Upper case is used to indicate that the actual name is left to the user.)
The ``signal`` and ``axes`` attributes of the
``data`` group define which items
are plottable data and which are *dimension scales*, respectively.
Expand All @@ -174,12 +177,14 @@
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.
* Each :ref:`NXdata` group will define one field as the default
plottable data. The value of the ``signal`` attribute names this field.
Additional fields may be used to describe the dimension scales and
uncertainities.
The ``auxiliary_signals`` attribute is a list of the other fields
to be plotted with the ``signal`` data.
* The plottable data may be of arbitrary rank up to a maximum
of ``NX_MAXRANK=32``.
of ``NX_MAXRANK=32`` (for compatibility with backend file formats).
* The plottable data will be named as the value of
the group ``signal`` attribute, such as::

Expand All @@ -191,7 +196,7 @@
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.
directly as a NeXus field or defined through a link.

* The group ``axes`` attribute will name the
*dimension scale* associated with the plottable data.
Expand Down Expand Up @@ -308,14 +313,14 @@

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
with a field named ``VARIABLE``. This pattern also
applies to other relationships such as ``VARIABLE_resolutions``
to connect additional data with a certain dataset.
to connect additional data with a certain field.
</doc>
<dimensions rank="1">
<doc>
A dimension scale must have a rank of 1 and has length ``n``,
same as ``variable``.
same as ``VARIABLE``.
</doc>
<dim index="1" value="n"/>
</dimensions>
Expand Down
66 changes: 35 additions & 31 deletions base_classes/NXentry.nxdl.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
<?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
Expand All @@ -21,8 +21,8 @@
#
# For further information, see http://www.nexusformat.org
-->
<definition name="NXentry"
type="group"
<definition name="NXentry"
type="group"
extends="NXobject"
category="base"
xmlns="http://definition.nexusformat.org/nxdl/3.1"
Expand All @@ -32,55 +32,59 @@

<attribute name="default">
<doc>
.. index:: find the default plottable data
.. index:: plotting
.. index:: default attribute value

Declares which :ref:`NXdata` group contains the data
to be shown by default.
It is needed to resolve ambiguity when more than
It is used to resolve ambiguity when
one :ref:`NXdata` group exists.
The value is the name of the default :ref:`NXdata` group.
The value :ref:`names &lt;validItemName>` a child group. If that group
itself has a ``default`` attribute, continue this chain until an
:ref:`NXdata` group is reached.

For more information about how NeXus identifies the default
plottable data, see the
:ref:`Find Plottable Data, v3 &lt;Find-Plottable-Data-v3&gt;`
section.
</doc>
</attribute>

<doc>
(**required**) :ref:`NXentry` describes the measurement.
(**required**) :ref:`NXentry` describes the measurement.

The top-level NeXus group which contains all the data and associated
information that comprise a single measurement.
information that comprise a single measurement.
It is mandatory that there is at least one
group of this type in the NeXus file. </doc>

<group type="NXdata">
<doc>
The data group

.. note:: Before the NIAC2016 meeting [#]_, at least one
:ref:`NXdata` group was required in each :ref:`NXentry` group.
At the NIAC2016 meeting, it was decided to make :ref:`NXdata`
an optional group in :ref:`NXentry` groups for data files that
At the NIAC2016 meeting, it was decided to make :ref:`NXdata`
an optional group in :ref:`NXentry` groups for data files that
do not use an application definition.
It is recommended strongly that all NeXus data files provide
a NXdata group.
It is permissable to omit the NXdata group only when
It is recommended strongly that all NeXus data files provide
a NXdata group.
It is permissable to omit the NXdata group only when
defining the default plot is not practical or possible
from the available data.
For example, neutron event data may not have anything that

For example, neutron event data may not have anything that
makes a useful plot without extensive processing.

Certain application definitions override this decision and
require an :ref:`NXdata` group
in the :ref:`NXentry` group. The ``minOccurs=0`` attribute
in the application definition will indicate the
in the application definition will indicate the
:ref:`NXdata` group
is optional, otherwise, it is required.
.. [#] NIAC2016:

.. [#] NIAC2016:
https://www.nexusformat.org/NIAC2016.html,
https://github.com/nexusformat/NIAC/issues/16

Expand All @@ -96,8 +100,8 @@
</field>
<field name="experiment_identifier">
<doc>
Unique identifier for the experiment,
defined by the facility,
Unique identifier for the experiment,
defined by the facility,
possibly linked to the proposals
</doc>
</field>
Expand Down Expand Up @@ -130,13 +134,13 @@
<field name="definition">
<doc>
(alternate use: see same field in :ref:`NXsubentry` for preferred)

Official NeXus NXDL schema to which this entry conforms.

This field is provided so that :ref:`NXentry` can be the overlay position
in a NeXus data file for an application definition and its
in a NeXus data file for an application definition and its
set of groups, fields, and attributes.

*It is advised* to use :ref:`NXsubentry`, instead, as the overlay position.
</doc>
<attribute name="version"><doc>NXDL version number</doc></attribute>
Expand All @@ -145,7 +149,7 @@
<field name="definition_local" deprecated="see same field in :ref:`NXsubentry` for preferred use">
<doc>
Local NXDL schema extended from the entry
specified in the ``definition`` field.
specified in the ``definition`` field.
This contains any locally-defined,
additional fields in the entry.
</doc>
Expand Down Expand Up @@ -202,7 +206,7 @@
<attribute name="type">
<doc>The mime type should be an ``image/*``</doc>
<enumeration>
<!--
<!--
This is not perfect.
How do we set a default value for the type attribute?
-->
Expand Down
30 changes: 17 additions & 13 deletions base_classes/NXroot.nxdl.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
<?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
Expand All @@ -24,13 +24,13 @@
<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" category="base"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
name="NXroot"
name="NXroot"
type="group" extends="NXobject">
<doc>Definition of the root NeXus group.</doc>
<attribute name="NX_class">
<doc>
The root of any NeXus data file is an ``NXroot`` class
(no other choice is allowed for a valid NeXus data file).
The root of any NeXus data file is an ``NXroot`` class
(no other choice is allowed for a valid NeXus data file).
This attribute cements that definition.
</doc>
<enumeration>
Expand All @@ -49,7 +49,7 @@
<attribute name="NeXus_version">
<doc>
Version of NeXus API used in writing the file.

Only used when the NAPI has written the file.
Note that this is different from the version of the
base class or application definition version number.
Expand All @@ -61,7 +61,7 @@
<attribute name="HDF5_Version">
<doc>
Version of HDF5 library used in writing the file.

Note this attribute is spelled with uppercase "V",
different than other version attributes.
</doc>
Expand All @@ -83,14 +83,18 @@
</group>
<attribute name="default">
<doc>
.. index:: find the default plottable data
.. index:: plotting

Declares which :ref:`NXentry` group contains
.. index:: default attribute value

Declares which :ref:`NXentry` group contains
the data to be shown by default.
It is needed to resolve ambiguity when
more than one :ref:`NXentry` group exists.
The value is the name of the default :ref:`NXentry` group.

It is used to resolve ambiguity when
more than one :ref:`NXentry` group exists.
The value :ref:`names &lt;validItemName>` the default :ref:`NXentry` group. The
value must be the name of a child of the current group. The child must be a
NeXus group or a link to a NeXus group.

It is recommended (as of NIAC2014) to use this attribute
to help define the path to the default dataset to be plotted.
See https://www.nexusformat.org/2014_How_to_find_default_data.html
Expand Down
14 changes: 9 additions & 5 deletions base_classes/NXsubentry.nxdl.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,17 @@

<attribute name="default">
<doc>
.. index:: find the default plottable data
.. index:: plotting
.. index:: default attribute value

Declares which :ref:`NXdata` group contains the data
to be shown by default.
It is needed to resolve ambiguity when more than
It is used to resolve ambiguity when
one :ref:`NXdata` group exists.
The value is the name of the default :ref:`NXdata` group.
The value :ref:`names &lt;validItemName>` the default :ref:`NXentry` group. The
value must be the name of a child of the current group. The child must be a
NeXus group or a link to a NeXus group.

For more information about how NeXus identifies the default
plottable data, see the
Expand Down Expand Up @@ -81,9 +85,9 @@
</field>
<field name="experiment_identifier">
<doc>
Unique identifier for the experiment, defined by
the facility, possibly linked to the proposals
</doc>
Unique identifier for the experiment, defined by
the facility, possibly linked to the proposals
</doc>
</field>
<field name="experiment_description">
<doc>Brief summary of the experiment, including key objectives.</doc>
Expand Down
Loading

0 comments on commit e045360

Please sign in to comment.