Skip to content

Commit

Permalink
resolve similar methods to identify data for the default plot
Browse files Browse the repository at this point in the history
  • Loading branch information
@prjemian
prjemian committed Jul 16, 2014
1 parent ff09f29 commit f10ceb8
Show file tree
Hide file tree
Showing 2 changed files with 126 additions and 73 deletions.
121 changes: 81 additions & 40 deletions manual/source/datarules.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -494,46 +494,87 @@ time-of-flight monitors.
Find the plottable data
#######################

Any program whose aim is to identify plottable data should use the
following procedure:

#. Open the first top level NeXus group with class
``NXentry``.

#. Open the first NeXus group with class
``NXdata``.

#. Loop through NeXus fields in this group searching for the item
with attribute
``signal="1"``
indicating this field has the plottable data.

#. Check to see if this field has an attribute called
``axes``. If so, the attribute value contains a colon (or comma)
delimited list (in the C-order of the data array) with the names
of the
:index:`dimension scales <dimension scale>`
associated with the plottable data. And
then you can skip the next two steps.

#. If the ``axes`` attribute is not defined, search for the
one-dimensional NeXus fields with attribute ``primary=1``.

#. These are the dimension scales to label
the axes of each dimension of the data.

#. Link each dimension scale
to the respective data dimension by
the ``axis`` attribute (``axis=1``, ``axis=2``,
... up to the :index:`rank <rank>` of the data).

#. If necessary, close the
``NXdata``
group, open the next one and repeat steps 3 to 6.

#. If necessary, close the
``NXentry``
group, open the next one and repeat steps 2 to 7.
Any program whose aim is to identify the default plottable data
should use the following procedure:

#. Start at the top level of the NeXus data file.

#. Loop through the groups with class ``NXentry``
until the next step succeeds.

#. Open the NXentry group and loop through the subgroups
with class ``NXdata`` until the next step succeeds.

#. Open the NXdata group and loop through the fields for the one field
with attribute ``signal="1"``.
Note: There should be *only one* field that matches.

This is default plottable data.

#. If this field has an attribute ``axes``:

#. The ``axes`` attribute value contains a colon (or comma)
delimited list (in the C-order of the data array) with
the names of the
:index:`dimension scales <dimension scale>`
associated with the plottable data.
Such as: ``axes="polar_angle:time_of_flight"``

#. Parse ``axes`` and open the datasets to describe your
:index:`dimension scales <dimension scale>`

#. If this field has no attribute ``axes``:

#. Search for datasets with attributes ``axis=1``, ``axis=2``, etc.

These are the fields describing your axis. There may be
several fields for any axis, i.e. there may be multiple
fields with the attribute ``axis=1``. Among them the
field with the attribute ``primary=1`` is the preferred one.
All others are alternative :index:`dimension scales <dimension scale>`.

#. Having found the default plottable data and its dimension scales:
make the plot.

.. the previous description
#. Open the first top level NeXus group with class
``NXentry``.
#. Open the first NeXus group with class
``NXdata``.
#. Loop through NeXus fields in this group searching for the item
with attribute
``signal="1"``
indicating this field has the plottable data.
#. Check to see if this field has an attribute called
``axes``. If so, the attribute value contains a colon (or comma)
delimited list (in the C-order of the data array) with the names
of the
:index:`dimension scales <dimension scale>`
associated with the plottable data. And
then you can skip the next two steps.
#. If the ``axes`` attribute is not defined, search for the
one-dimensional NeXus fields with attribute ``primary=1``.
#. These are the dimension scales to label
the axes of each dimension of the data.
#. Link each dimension scale
to the respective data dimension by
the ``axis`` attribute (``axis=1``, ``axis=2``,
... up to the :index:`rank <rank>` of the data).
#. If necessary, close the
``NXdata``
group, open the next one and repeat steps 3 to 6.
#. If necessary, close the
``NXentry``
group, open the next one and repeat steps 2 to 7.
Consult the :ref:`NeXus API <Introduction-NAPI>`
section, which describes the routines available to program these
Expand Down
78 changes: 45 additions & 33 deletions manual/source/design.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -308,6 +308,9 @@ showing an external file link in HDF5:
NeXus Base Classes
==================

.. index:: NX; used as NX class prefix
.. index:: rules; NX prefix

Data groups often describe objects in the experiment (monitors, detectors,
monochromators, etc.), so that the contents (both data fields and/or other data
groups) comprise the properties of that object. NeXus has defined a set of standard
Expand Down Expand Up @@ -387,45 +390,54 @@ annotate or in a ``NXcollection``. All of the base classes are documented in the
The most notable special base class (or *group* in NeXus) is ``NXdata``.
``NXdata`` is the answer to a basic motivation of NeXus to facilitate
automatic plotting of data.
``NXdata`` is designed to contain the main dataset and its associated dimension scales (axes)
of a NeXus data file. The
usage scenario is that an automatic data plotting program just opens a ``NXentry`` and then continues to search for any ``NXdata``
groups. These ``NXdata`` groups represent the plottable data. Here is the way an automatic plotting program ought to work:
``NXdata`` is designed to contain the main dataset and its associated
dimension scales (axes) of a NeXus data file.
The usage scenario is that an automatic data plotting program just
opens a ``NXentry`` and then continues to search for any ``NXdata``
groups. These ``NXdata`` groups represent the plottable data.
An algorithm for identifying the default plottable data
is :ref:`presented <Find-Plottable-Data>` in the
chapter titled :ref`DataRules`.

#. Search for ``NXentry`` groups

#. Open an ``NXentry``

#. Search for ``NXdata`` groups
.. the previous description
Here is the way an automatic plotting program ought to work:
#. Open an ``NXdata`` group
#. Search for ``NXentry`` groups
#. Identify the plottable data.
#. Open an ``NXentry``
#. Search for a dataset with attribute ``signal=1``. This is your main dataset.
(There should be *only one* dataset that matches.)

#. Try to read the ``axes`` attribute of the main dataset, if it exists.

#. The value of ``axes`` is a colon- or comma-separated list of the datasets describing the
:index:`dimension scales <dimension scale>`
(such as ``axes="polar_angle:time_of_flight"``).

#. Parse ``axes`` and open the datasets to describe your
:index:`dimension scales <dimension scale>`

#. If ``axes`` does not exist:

#. Search for datasets with attributes ``axis=1``, ``axis=2``, etc.
These are the datasets describing your axis. There may be
several datasets for any axis, i.e. there may be multiple datasets with the attribute ``axis=1``. Among them the dataset with the
attribute ``primary=1`` is the preferred one. All others are alternative :index:`dimension scales <dimension scale>`.

#. Open the datasets to describe your dimension scales.

#. Having found the default plottable data and
its :index:`dimension scales <dimension scale>`:
make the plot
#. Search for ``NXdata`` groups
#. Open an ``NXdata`` group
#. Identify the plottable data.
#. Search for a dataset with attribute ``signal=1``. This is your main dataset.
(There should be *only one* dataset that matches.)
#. Try to read the ``axes`` attribute of the main dataset, if it exists.
#. The value of ``axes`` is a colon- or comma-separated list of the datasets describing the
:index:`dimension scales <dimension scale>`
(such as ``axes="polar_angle:time_of_flight"``).
#. Parse ``axes`` and open the datasets to describe your
:index:`dimension scales <dimension scale>`
#. If ``axes`` does not exist:
#. Search for datasets with attributes ``axis=1``, ``axis=2``, etc.
These are the datasets describing your axis. There may be
several datasets for any axis, i.e. there may be multiple datasets with the attribute ``axis=1``. Among them the dataset with the
attribute ``primary=1`` is the preferred one. All others are alternative :index:`dimension scales <dimension scale>`.
#. Open the datasets to describe your dimension scales.
#. Having found the default plottable data and
its :index:`dimension scales <dimension scale>`:
make the plot.
.. _where.to.store.metadata:
Expand Down

0 comments on commit f10ceb8

Please sign in to comment.