From a6102a6d742f9366515a208289fc79862b4c1828 Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Sat, 18 Jun 2022 13:59:28 -0500 Subject: [PATCH] DOC #879 reference from NeXus classes page --- manual/source/classes/index.rst | 173 ++++++++++++++++++-------------- 1 file changed, 96 insertions(+), 77 deletions(-) diff --git a/manual/source/classes/index.rst b/manual/source/classes/index.rst index e84710738..83b5f6ba4 100644 --- a/manual/source/classes/index.rst +++ b/manual/source/classes/index.rst @@ -10,84 +10,103 @@ Definitions of NeXus classes. These are split into base_classes (low level objec application definitions (groupings of objects for a particular technique) and contributed_definitions (proposed definitions from the community) -:ref:`base classes ` - NeXus base class definitions define the set of terms that - *might* be used in an instance of that class. - Consider the base classes as a set of *components* - that are used to construct a data file. - - Base class definitions are permissive rather than restrictive. - While the terms defined aim to cover most possible use cases, - and to codify the spelling and meaning of such terms, - the class specifications cannot list all acceptable groups and fields. - To be able to progress the NeXus standard, additional data - (groups, fields, attributes) are acceptable in NeXus HDF5 data files. - - Users are encouraged to find the best *defined* location in which - to place their information. It is understood there is not a - predefined place for all possible data. - - Validation procedures should treat such additional items - (not covered by a base class specification) as notes or warnings - rather than errors. - -:ref:`application definitions ` - NeXus application definitions define the *minimum* - set of terms that - *must* be used in an instance of that class. - Application definitions also may define terms that - are optional in the NeXus data file. - - As in base classes (see above), additional terms that are - not described by the application definition may be added to - data files that incorporate or adhere to application definitions. - - .. index:: link - - Use NeXus links liberally in data files to reduce duplication of data. - In application definitions involving raw data, - write the raw data in the :ref:`NXinstrument` tree and then link to it - from the location(s) defined in the relevant application definition. - See figure :ref:`NeXus Multi Method Hierarchy ` - for an example. - - .. index:: subentry; NXsubentry, use of, multi-modal data - - To write a data file with an application definition, start with either - a :ref:`NXentry` (or :ref:`NXsubentry`) group [#]_ and write the name of the - application definition in the ``definition`` field. Then write data into - this group according to the specifications of the application definition. - - .. [#] For data files involving just an application definition, use - the :ref:`NXentry` group. Such as this structure:: - - entry:NXentry +The complete :index:`!vocabulary`` of terms (names of groups, fields, attributes, and +links) used in NeXus NXDL files is available for download. See this table for +the different formats available: + +========================================= ============================================ +download file description +========================================= ============================================ +:download:`/_static/nxdl_vocabulary.html` Human-readable HTML list of anchors, by vocabulary term, with links to the manual. +:download:`/_static/nxdl_vocabulary.json` vocabulary list by key in [JSON](https://www.w3schools.com/whatis/whatis_json.asp) format +:download:`/_static/nxdl_vocabulary.txt` list of all anchors, sorted alphabetically +:download:`/_static/nxdl_vocabulary.yml` vocabulary list by key in [YAML](https://yaml.org/) format +========================================= ============================================ + +Base classes +------------------ + +NeXus :ref:`base class ` definitions define the set of terms that +*might* be used in an instance of that class. +Consider the base classes as a set of *components* +that are used to construct a data file. + +Base class definitions are permissive rather than restrictive. +While the terms defined aim to cover most possible use cases, +and to codify the spelling and meaning of such terms, +the class specifications cannot list all acceptable groups and fields. +To be able to progress the NeXus standard, additional data +(groups, fields, attributes) are acceptable in NeXus HDF5 data files. + +Users are encouraged to find the best *defined* location in which +to place their information. It is understood there is not a +predefined place for all possible data. + +Validation procedures should treat such additional items +(not covered by a base class specification) as notes or warnings +rather than errors. + +Application Definitions +------------------------ + +NeXus :ref:`application definitions ` define the *minimum* +set of terms that +*must* be used in an instance of that class. +Application definitions also may define terms that +are optional in the NeXus data file. + +As in base classes (see above), additional terms that are +not described by the application definition may be added to +data files that incorporate or adhere to application definitions. + +.. index:: link + +Use NeXus links liberally in data files to reduce duplication of data. +In application definitions involving raw data, +write the raw data in the :ref:`NXinstrument` tree and then link to it +from the location(s) defined in the relevant application definition. +See figure :ref:`NeXus Multi Method Hierarchy ` +for an example. + +.. index:: subentry; NXsubentry, use of, multi-modal data + +To write a data file with an application definition, start with either +a :ref:`NXentry` (or :ref:`NXsubentry`) group [#]_ and write the name of the +application definition in the ``definition`` field. Then write data into +this group according to the specifications of the application definition. + +.. [#] For data files involving just an application definition, use + the :ref:`NXentry` group. Such as this structure:: + + entry:NXentry + definition="NXsas" + + For files that describe multi-modal + data and require use of two or more application definitions + (such as :ref:`NXsas` *and* :ref:`NXcanSAS`), you must place each + application definition in a :ref:`NXsubentry` of the :ref:`NXentry` group. + Such as this structure:: + + entry:NXentry + raw:NXsubentry definition="NXsas" - - For files that describe multi-modal - data and require use of two or more application definitions - (such as :ref:`NXsas` *and* :ref:`NXcanSAS`), you must place each - application definition in a :ref:`NXsubentry` of the :ref:`NXentry` group. - Such as this structure:: - - entry:NXentry - raw:NXsubentry - definition="NXsas" - reduced:NXsubentry - definition="NXcanSAS" - fluo:NXsubentry - definition="NXfluo" - - If you anticipate your data file will eventually require an additional - application definition, you should start with each application definition - in a :ref:`NXsubentry` group. - -:ref:`contributed definitions ` - NXDL files in the NeXus contributed definitions include propositions from - the community for NeXus base classes or application definitions, as well - as other NXDL files for long-term archival by NeXus. Consider the contributed - definitions as either in *incubation* or a special - case not for general use. + reduced:NXsubentry + definition="NXcanSAS" + fluo:NXsubentry + definition="NXfluo" + + If you anticipate your data file will eventually require an additional + application definition, you should start with each application definition + in a :ref:`NXsubentry` group. + +Contributed Definitions +------------------------ + +NXDL files in the NeXus :ref:`contributed definitions ` include propositions from +the community for NeXus base classes or application definitions, as well +as other NXDL files for long-term archival by NeXus. Consider the contributed +definitions as either in *incubation* or a special +case not for general use. .. toctree:: :hidden: