From f10ceb8386a6f8b0a831a03514aaee5a37635727 Mon Sep 17 00:00:00 2001 From: Pete Jemian Date: Wed, 16 Jul 2014 14:26:28 -0500 Subject: [PATCH] resolve similar methods to identify data for the default plot --- manual/source/datarules.rst | 121 ++++++++++++++++++++++++------------ manual/source/design.rst | 78 +++++++++++++---------- 2 files changed, 126 insertions(+), 73 deletions(-) diff --git a/manual/source/datarules.rst b/manual/source/datarules.rst index 5b6034718..6fb558f65 100644 --- a/manual/source/datarules.rst +++ b/manual/source/datarules.rst @@ -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 ` - 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 ` 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 ` + 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 ` + + #. 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 `. + +#. 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 ` + 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 ` 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 ` section, which describes the routines available to program these diff --git a/manual/source/design.rst b/manual/source/design.rst index c61d3192f..e3c38161a 100644 --- a/manual/source/design.rst +++ b/manual/source/design.rst @@ -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 @@ -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 ` 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 ` - (such as ``axes="polar_angle:time_of_flight"``). - - #. Parse ``axes`` and open the datasets to describe your - :index:`dimension scales ` - - #. 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 `. - - #. Open the datasets to describe your dimension scales. - -#. Having found the default plottable data and - its :index:`dimension scales `: - 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 ` + (such as ``axes="polar_angle:time_of_flight"``). + + #. Parse ``axes`` and open the datasets to describe your + :index:`dimension scales ` + + #. 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 `. + + #. Open the datasets to describe your dimension scales. + + #. Having found the default plottable data and + its :index:`dimension scales `: + make the plot. .. _where.to.store.metadata: