.. auto-generated by script: ../../utils/nxdl_desc2rst.py ============================= NXDL Elements and Field Types ============================= The documentation in this section has been obtained directly from the NXDL Schema file: *nxdl.xsd*. First, the basic elements are defined in alphabetical order. Attributes to an element are indicated immediately following the element and are preceded with an "@" symbol, such as **@attribute**. Then, the common data types used within the NXDL specification are defined. Pay particular attention to the rules for *validItemName* and *validNXClassName*. .. 2010-11-29,PRJ: This contains a lot of special case code to lay out the NXDL chapter. It could be cleaner but that would also involve some cooperation on anyone who edits nxdl.xsd which is sure to break. The special case ensures the parts come out in the chosen order. BUT, it is possible that new items in nxdl.xsd will not automatically go in the manual. Can this be streamlined with some common methods? Also, there is probably too much documentation in nxdl.xsd. Obscures the function. .. index:: see: attribute; NXDL attribute ! single: NXDL elements .. _NXDL.elements: NXDL Elements ============= .. index:: ! attribute (NXDL element) .. _attribute: attribute --------- An ``attribute`` element can *only* be a child of a ``field`` or ``group`` element. It is used to define *attribute* elements to be used and their data types and possibly an enumeration of allowed values. For more details, see: :ref:`NXDL.data.type.attributeType` .. compound:: .. _fig.nxdl_attribute: .. figure:: img/nxdl/nxdl_attribute.png :alt: fig.nxdl/nxdl_attribute :width: 80% Graphical representation of the NXDL ``attribute`` element .. Images of NXDL structure are generated from nxdl.xsd source using the Eclipse XML Schema Editor (Web Tools Platform). Open the nxdl.xsd file and choose the "Design" tab. Identify the structure to be documented and double-click to expand as needed to show the detail. Use the XSD > "Export Diagram as Image ..." menu item (also available as button in top toolbar). Set the name: "nxdl_attribute.png" and move the file into the correct location using your operating system's commands. Commit the revision to version control. .. index:: ! choice (NXDL element) .. _choice: choice ------ A ``choice`` element is used when a named group might take one of several possible NeXus base classes. Logically, it must have at least two group children. For more details, see: :ref:`NXDL.data.type.choiceType` .. index:: ! definition (NXDL element) .. _definition: definition ---------- A ``definition`` element can *only* be used at the root level of an NXDL specification. Note: Due to the large number of attributes of the ``definition`` element, they have been omitted from the figure below. For more details, see: :ref:`NXDL.data.type.definition`, :ref:`NXDL.data.type.definitionType`, and :ref:`NXDL.data.type.definitionTypeAttr` .. compound:: .. _fig.nxdl_definition: .. figure:: img/nxdl/nxdl_definition.png :alt: fig.nxdl/nxdl_definition :width: 80% Graphical representation of the NXDL ``definition`` element .. Images of NXDL structure are generated from nxdl.xsd source using the Eclipse XML Schema Editor (Web Tools Platform). Open the nxdl.xsd file and choose the "Design" tab. Identify the structure to be documented and double-click to expand as needed to show the detail. Use the XSD > "Export Diagram as Image ..." menu item (also available as button in top toolbar). Set the name: "nxdl_definition.png" and move the file into the correct location using your operating system's commands. Commit the revision to version control. .. index:: ! dimensions (NXDL element) .. _dimensions: dimensions ---------- The ``dimensions`` element describes the *shape* of an array. It is used *only* as a child of a ``field`` element. For more details, see: :ref:`NXDL.data.type.dimensionsType` .. compound:: .. _fig.nxdl_dimensions: .. figure:: img/nxdl/nxdl_dimensions.png :alt: fig.nxdl/nxdl_dimensions :width: 80% Graphical representation of the NXDL ``dimensions`` element .. Images of NXDL structure are generated from nxdl.xsd source using the Eclipse XML Schema Editor (Web Tools Platform). Open the nxdl.xsd file and choose the "Design" tab. Identify the structure to be documented and double-click to expand as needed to show the detail. Use the XSD > "Export Diagram as Image ..." menu item (also available as button in top toolbar). Set the name: "nxdl_dimensions.png" and move the file into the correct location using your operating system's commands. Commit the revision to version control. .. index:: ! doc (NXDL element) .. _doc: doc --- A ``doc`` element can be a child of most NXDL elements. In most cases, the content of the ``doc`` element will also become part of the NeXus manual. :element: {any}: In documentation, it may be useful to use an element that is not directly specified by the NXDL language. The *any* element here says that one can use any element at all in a ``doc`` element and NXDL will not process it but pass it through. For more details, see: :ref:`NXDL.data.type.docType` .. compound:: .. _fig.nxdl_doc: .. figure:: img/nxdl/nxdl_doc.png :alt: fig.nxdl/nxdl_doc :width: 80% Graphical representation of the NXDL ``doc`` element .. Images of NXDL structure are generated from nxdl.xsd source using the Eclipse XML Schema Editor (Web Tools Platform). Open the nxdl.xsd file and choose the "Design" tab. Identify the structure to be documented and double-click to expand as needed to show the detail. Use the XSD > "Export Diagram as Image ..." menu item (also available as button in top toolbar). Set the name: "nxdl_doc.png" and move the file into the correct location using your operating system's commands. Commit the revision to version control. .. index:: ! enumeration (NXDL element) .. _enumeration: enumeration ----------- An ``enumeration`` element can *only* be a child of a ``field`` or ``attribute`` element. It is used to restrict the available choices to a predefined list, such as to control varieties in spelling of a controversial word (such as *metre* vs. *meter*). For more details, see: :ref:`NXDL.data.type.enumerationType` .. compound:: .. _fig.nxdl_enumeration: .. figure:: img/nxdl/nxdl_enumeration.png :alt: fig.nxdl/nxdl_enumeration :width: 80% Graphical representation of the NXDL ``enumeration`` element .. Images of NXDL structure are generated from nxdl.xsd source using the Eclipse XML Schema Editor (Web Tools Platform). Open the nxdl.xsd file and choose the "Design" tab. Identify the structure to be documented and double-click to expand as needed to show the detail. Use the XSD > "Export Diagram as Image ..." menu item (also available as button in top toolbar). Set the name: "nxdl_enumeration.png" and move the file into the correct location using your operating system's commands. Commit the revision to version control. .. index:: ! field (NXDL element) .. _field: field ----- The ``field`` element provides the value of a named item. Many different attributes are available to further define the ``field``. Some of the attributes are not allowed to be used together (such as ``axes`` and ``axis``); see the documentation of each for details. It is used *only* as a child of a ``group`` element. For more details, see: :ref:`NXDL.data.type.fieldType` .. compound:: .. _fig.nxdl_field: .. figure:: img/nxdl/nxdl_field.png :alt: fig.nxdl/nxdl_field :width: 80% Graphical representation of the NXDL ``field`` element .. Images of NXDL structure are generated from nxdl.xsd source using the Eclipse XML Schema Editor (Web Tools Platform). Open the nxdl.xsd file and choose the "Design" tab. Identify the structure to be documented and double-click to expand as needed to show the detail. Use the XSD > "Export Diagram as Image ..." menu item (also available as button in top toolbar). Set the name: "nxdl_field.png" and move the file into the correct location using your operating system's commands. Commit the revision to version control. .. index:: ! group (NXDL element) .. _group: group ----- A ``group`` element can *only* be a child of a ``definition`` or ``group`` element. It describes a common level of organization in a NeXus data file, similar to a subdirectory in a file directory tree. For more details, see: :ref:`NXDL.data.type.groupType` .. compound:: .. _fig.nxdl_group: .. figure:: img/nxdl/nxdl_group.png :alt: fig.nxdl/nxdl_group :width: 80% Graphical representation of the NXDL ``group`` element .. Images of NXDL structure are generated from nxdl.xsd source using the Eclipse XML Schema Editor (Web Tools Platform). Open the nxdl.xsd file and choose the "Design" tab. Identify the structure to be documented and double-click to expand as needed to show the detail. Use the XSD > "Export Diagram as Image ..." menu item (also available as button in top toolbar). Set the name: "nxdl_group.png" and move the file into the correct location using your operating system's commands. Commit the revision to version control. .. index:: ! link (NXDL element) .. _link: link ---- .. index:: single: link target A ``link`` element can *only* be a child of a ``definition``, ``field``, or ``group`` element. It describes the path to the original source of the parent ``definition``, ``field``, or ``group``. For more details, see: :ref:`NXDL.data.type.linkType` .. compound:: .. _fig.nxdl_link: .. figure:: img/nxdl/nxdl_link.png :alt: fig.nxdl/nxdl_link :width: 80% Graphical representation of the NXDL ``link`` element .. Images of NXDL structure are generated from nxdl.xsd source using the Eclipse XML Schema Editor (Web Tools Platform). Open the nxdl.xsd file and choose the "Design" tab. Identify the structure to be documented and double-click to expand as needed to show the detail. Use the XSD > "Export Diagram as Image ..." menu item (also available as button in top toolbar). Set the name: "nxdl_link.png" and move the file into the correct location using your operating system's commands. Commit the revision to version control. .. index:: ! symbols (NXDL element) .. _symbols: symbols ------- A ``symbols`` element can *only* be a child of a ``definition`` element. It defines the array index symbols to be used when defining arrays as ``field`` elements with common dimensions and lengths. For more details, see: :ref:`NXDL.data.type.symbolsType` .. compound:: .. _fig.nxdl_symbols: .. figure:: img/nxdl/nxdl_symbols.png :alt: fig.nxdl/nxdl_symbols :width: 80% Graphical representation of the NXDL ``symbols`` element .. Images of NXDL structure are generated from nxdl.xsd source using the Eclipse XML Schema Editor (Web Tools Platform). Open the nxdl.xsd file and choose the "Design" tab. Identify the structure to be documented and double-click to expand as needed to show the detail. Use the XSD > "Export Diagram as Image ..." menu item (also available as button in top toolbar). Set the name: "nxdl_symbols.png" and move the file into the correct location using your operating system's commands. Commit the revision to version control. .. _NXDL.data.types.internal: NXDL Field Types (internal) =========================== Field types that define the NXDL language are described here. These data types are defined in the XSD Schema (``nxdl.xsd``) and are used in various parts of the Schema to define common structures or to simplify a complicated entry. While the data types are not intended for use in NXDL specifications, they define structures that may be used in NXDL specifications. .. Xpath = /xs:schema/xs:complexType[@name='attributeType'] .. index:: ! attributeType (NXDL data type) .. _NXDL.data.type.attributeType: attributeType ------------- Any new group or field may expect or require some common attributes. .. Could contain these elements: * ``doc`` * ``enumeration`` (This data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.) Attributes of attributeType +++++++++++++++++++++++++++ @name +++++ Name of the attribute (unique within the enclosing group). @optional +++++++++ Is this attribute *optional* (if **true**) or *required* (if **false**)? @recommended ++++++++++++ A synonym for optional, but with the recommendation that this attribute be specified. @type +++++ Type of the attribute. For ``group`` specifications, the class name. For ``field`` or ``attribute`` specifications, the NXDL field type. Elements of attributeType +++++++++++++++++++++++++ dimensions ++++++++++ dimensions of an attribute with data value(s) in a NeXus file doc +++ Description of this ``attribute``. This documentation will go into the manual. enumeration +++++++++++ An enumeration specifies the values to be used. .. Xpath = /xs:schema/xs:element[@name='definition'] .. index:: ! definition (NXDL data type) .. _NXDL.data.type.definition: definition ---------- A ``definition`` element is the ``group`` at the root of every NXDL specification. It may *only* appear at the root of an NXDL file and must only appear **once** for the NXDL to be *well-formed*. .. Xpath = /xs:schema/xs:complexType[@name='definitionType'] .. index:: ! definitionType (NXDL data type) .. _NXDL.data.type.definitionType: definitionType -------------- A ``definition`` is the root element of every NXDL definition. It may *only* appear at the root of an NXDL file and must only appear **once** for the NXDL to be *well-formed*. The ``definitionType`` defines the documentation, attributes, fields, and groups that will be used as children of the ``definition`` element. Could contain these elements: * ``attribute`` * ``doc`` * ``field`` * ``group`` * ``link`` Note that a ``definition`` element also includes the definitions of the ``basicComponent`` data type. (The ``definitionType`` data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.) Note that the first line of text in a ``doc`` element in a ``definition`` is used as a summary in the manual. Follow the pattern as shown in the base class NXDL files. Attributes of definitionType ++++++++++++++++++++++++++++ @category +++++++++ NXDL ``base`` definitions define the dictionary of terms to use for these components. All terms in a ``base`` definition are optional. NXDL ``application`` definitions define what is required for a scientific interest. All terms in an ``application`` definition are required. NXDL ``contributed`` definitions may be considered either base or applications. Contributed definitions must indicate their intended use, either as a base class or as an application definition. @extends ++++++++ The ``extends`` attribute allows this definition to *subclass* from another NXDL, otherwise ``extends="NXobject"`` should be used. @ignoreExtraAttributes ++++++++++++++++++++++ Only validate known attributes; do not not warn about unknowns. The ``ignoreExtraAttributes`` attribute is a flag to the process of validating NeXus data files. By setting ``ignoreExtraAttributes="true"``, presence of any undefined attributes in this class will not generate warnings during validation. Normally, validation will check all the attributes against their definition in the NeXus base classes and application definitions. Any items found that do not match the definition in the NXDL will generate a warning message. The ``ignoreExtraAttributes`` attribute should be used sparingly! @ignoreExtraFields ++++++++++++++++++ Only validate known fields; do not not warn about unknowns. The ``ignoreExtraFields`` attribute is a flag to the process of validating NeXus data files. By setting ``ignoreExtraFields="true"``, presence of any undefined fields in this class will not generate warnings during validation. Normally, validation will check all the fields against their definition in the NeXus base classes and application definitions. Any items found that do not match the definition in the NXDL will generate a warning message. The ``ignoreExtraFields`` attribute should be used sparingly! @ignoreExtraGroups ++++++++++++++++++ Only validate known groups; do not not warn about unknowns. The ``ignoreExtraGroups`` attribute is a flag to the process of validating NeXus data files. By setting ``ignoreExtraGroups="true"``, presence of any undefined groups in this class will not generate warnings during validation. Normally, validation will check all the groups against their definition in the NeXus base classes and application definitions. Any items found that do not match the definition in the NXDL will generate a warning message. The ``ignoreExtraGroups`` attribute should be used sparingly! @name +++++ The ``name`` of this NXDL file (case sensitive without the file extension). The name must be unique amongst all the NeXus base class, application, and contributed definitions. For the class to be adopted by the NIAC, the first two letters must be "``NX``" (in uppercase). Any other use must *not* begin with "``NX``" in any combination of upper or lower case. @restricts ++++++++++ The ``restricts`` attribute is a flag to the data validation. When ``restricts="1"``, any non-standard component found (and checked for validity against this NXDL specification) in a NeXus data file will be flagged as an error. If the ``restricts`` attribute is not present, any such situations will produce a warning. @svnid ++++++ (2014-08-19: deprecated since switch to GitHub version control) The identifier string from the subversion revision control system. This reports the time stamp and the revision number of this file. @type +++++ Must be ``type="group"`` Elements of definitionType ++++++++++++++++++++++++++ symbols +++++++ Use a ``symbols`` list to define each of the mnemonics that represent the length of each dimension in a vector or array. Groups under definitionType +++++++++++++++++++++++++++ In addition to an optional ``symbols`` list, a ``definition`` may contain any of the items allowed in a ``group``. .. Xpath = /xs:schema/xs:simpleType[@name='definitionTypeAttr'] .. index:: ! definitionTypeAttr (NXDL data type) .. _NXDL.data.type.definitionTypeAttr: definitionTypeAttr ------------------ Prescribes the allowed values for ``definition`` ``type`` attribute. (This data type is used internally in the NXDL schema to define a data type.) The value may be any one from this list only: * ``group`` * ``definition`` .. Xpath = /xs:schema/xs:complexType[@name='dimensionsType'] .. index:: ! dimensionsType (NXDL data type) .. _NXDL.data.type.dimensionsType: dimensionsType -------------- dimensions of a data element in a NeXus file (This data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.) Attributes of dimensionsType ++++++++++++++++++++++++++++ @rank +++++ Rank (number of dimensions) of the data structure. Value could be either an unsigned integer or a symbol as defined in the *symbol* table of the NXDL file. For example: ``a[5]`` has ``rank="1"`` while ``b[8,5,6,4]`` has ``rank="4"``. See https://en.wikipedia.org/wiki/Rank_%28computer_programming%29 for more details. Elements of dimensionsType ++++++++++++++++++++++++++ dim +++ Specify the parameters for each index of the ``dimensions`` element with a ``dim`` element. The number of ``dim`` entries should be equal to the ``rank`` of the array. For example, these terms describe a 2-D array with lengths (``nsurf``, ``nwl``): .. code-block:: xml :linenos: The ``value`` attribute is used by NXDL and also by the NeXus data file validation tools to associate and coordinate the same array length across multiple fields in a group. @incr ~~~~~ Deprecated: 2016-11-23 telco (https://github.com/nexusformat/definitions/issues/330) The dimension specification is related to the ``refindex`` axis within the ``ref`` field by an offset of ``incr``. Requires ``ref`` and ``refindex`` attributes to be present. @index ~~~~~~ Number or symbol indicating which axis (subscript) is being described, ranging from 1 up to ``rank`` (rank of the data structure). For example, given an array ``A[i,j,k]``, ``index="1"`` would refer to the ``i`` axis (subscript). (``NXdata`` uses ``index="0"`` to indicate a situation when the specific index is not known *a priori*.) @ref ~~~~ Deprecated: 2016-11-23 telco (https://github.com/nexusformat/definitions/issues/330) The dimension specification is the same as that in the ``ref`` field, specified either by a relative path, such as ``polar_angle`` or ``../Qvec`` or absolute path, such as ``/entry/path/to/follow/to/ref/field``. @refindex ~~~~~~~~~ Deprecated: 2016-11-23 telco (https://github.com/nexusformat/definitions/issues/330) The dimension specification is the same as the ``refindex`` axis within the ``ref`` field. Requires ``ref`` attribute to be present. @required ~~~~~~~~~ This dimension is required (true: default) or not required (false). The default value is ``true``. When ``required="false"`` is specified, all subsequent ````. Could contain these elements: * ``doc`` * ``item`` (This data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.) :: source operating mode for storage rings for storage rings Elements of enumerationType +++++++++++++++++++++++++++ item ++++ One of the prescribed values. Use the ``value`` attribute. Defines the value of one selection for an ``enumeration`` list. Each enumerated item must have a value (it cannot have an empty text node). @value ~~~~~~ The value of ``value`` of an ``enumItem`` is defined as an attribute rather than a name. doc ~~~ Individual items can be documented but this documentation might not be printed in the *NeXus Reference Guide*. .. Xpath = /xs:schema/xs:complexType[@name='fieldType'] .. index:: ! fieldType (NXDL data type) .. _NXDL.data.type.fieldType: fieldType --------- A ``field`` declares a new element in the component being defined. A ``field`` is synonymous with the HDF4 SDS (Scientific Data Set) and the HDF5 *dataset* terms. Could contain these elements: * ``attribute`` * ``dimensions`` * ``doc`` * ``enumeration`` Note that a ``field`` element also includes the definitions of the ``basicComponent`` data type. (The ``fieldType`` data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.) @axes +++++ NOTE: Use of the ``axes`` attribute for a *field* is discouraged. It is for legacy support. You should use the ``axes`` group attribute (such as in NXdata) instead. This attribute contains a 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). When there is only one item in the string array, it is acceptable to set the value to the one string. In such case, it is not necessary to make it an array of one string. Presence of the ``axes`` attribute means this field is an ordinate. @axis +++++ NOTE: Use of this attribute is discouraged. It is for legacy support. You should use the ``axes`` group attribute (such as in NXdata) instead. Presence of the ``axis`` attribute means this field is an abscissa. The attribute value is an integer indicating this field as an axis that is part of the data set. The data set is a field with the attribute ``signal=1`` in the same group. The value can range from 1 up to the number of independent axes (abscissae) in the data set. A value of ``axis=1``" indicates that this field contains the data for the first independent axis. For example, the X axis in an XY data set. A value of ``axis=2`` indicates that this field contains the data for the second independent axis. For example, the Y axis in a 2-D data set. A value of ``axis=3`` indicates that this field contains the data for the third independent axis. For example, the Z axis in a 3-D data set. A field with an ``axis`` attribute should not have a ``signal`` attribute. @data_offset ++++++++++++ The ``stride`` and ``data_offset`` attributes are used together to index the array of data items in a multi-dimensional array. They may be used as an alternative method to address a data array that is not stored in the standard NeXus method of "C" order. The ``data_offset`` attribute determines the starting coordinates of the data array for each dimension. See https://support.hdfgroup.org/HDF5/Tutor/phypereg.html or *4. Dataspace Selection Operations* in https://portal.hdfgroup.org/display/HDF5/Dataspaces The ``data_offset`` attribute contains a comma-separated list of integers. (In addition to the required comma delimiter, whitespace is also allowed to improve readability.) The number of items in the list is equal to the rank of the data being stored. The value of each item is the offset in the array of the first data item of that subscript of the array. @interpretation +++++++++++++++ This instructs the consumer of the data what the last dimensions of the data are. It allows plotting software to work out the natural way of displaying the data. For example a single-element, energy-resolving, fluorescence detector with 512 bins should have ``interpretation="spectrum"``. If the detector is scanned over a 512 x 512 spatial grid, the data reported will be of dimensions: 512 x 512 x 512. In this example, the initial plotting representation should default to data of the same dimensions of a 512 x 512 pixel ``image`` detector where the images where taken at 512 different pressure values. In simple terms, the allowed values mean: * ``scalar`` = 0-D data to be plotted * ``scaler`` = DEPRECATED, use ``scalar`` * ``spectrum`` = 1-D data to be plotted * ``image`` = 2-D data to be plotted * ``rgb-image`` = 3-D data to be plotted * ``rgba-image`` = 3-D data to be plotted * ``hsl-image`` = 3-D data to be plotted * ``hsla-image`` = 3-D data to be plotted * ``cmyk-image`` = 3-D data to be plotted * ``vertex`` = 3-D data to be plotted @long_name ++++++++++ Descriptive name for this field (may include whitespace and engineering units). Often, the long_name (when defined) will be used as the axis label on a plot. @maxOccurs ++++++++++ Defines the maximum number of times this element may be used. Its value is confined to zero or greater. Must be greater than or equal to the value for the "minOccurs" attribute. A value of "unbounded" is allowed. @minOccurs ++++++++++ Defines the minimum number of times this ``field`` may be used. Its value is confined to zero or greater. Must be less than or equal to the value for the "maxOccurs" attribute. @nameType +++++++++ This interprets the name attribute as: * ``specified`` = use as specified * ``any`` = can be any name not already used in group @optional +++++++++ A synonym for minOccurs=0. @primary ++++++++ Integer indicating the priority of selection of this field for plotting (or visualization) as an axis. Presence of the ``primary`` attribute means this field is an abscissa. @recommended ++++++++++++ A synonym for optional, but with the recommendation that this ``field`` be specified. @signal +++++++ Presence of the ``signal`` attribute means this field is an ordinate. Integer marking this field as plottable data (ordinates). The value indicates the priority of selection or interest. Some facilities only use ``signal=1`` while others use ``signal=2`` to indicate plottable data of secondary interest. Higher numbers are possible but not common and interpretation is not standard. A field with a ``signal`` attribute should not have an ``axis`` attribute. @stride +++++++ The ``stride`` and ``data_offset`` attributes are used together to index the array of data items in a multi-dimensional array. They may be used as an alternative method to address a data array that is not stored in the standard NeXus method of "C" order. The ``stride`` list chooses array locations from the data array with each value in the ``stride`` list determining how many elements to move in each dimension. Setting a value in the ``stride`` array to 1 moves to each element in that dimension of the data array, while setting a value of 2 in a location in the ``stride`` array moves to every other element in that dimension of the data array. A value in the ``stride`` list may be positive to move forward or negative to step backward. A value of zero will not step (and is of no particular use). See https://support.hdfgroup.org/HDF5/Tutor/phypereg.html or *4. Dataspace Selection Operations* in https://portal.hdfgroup.org/display/HDF5/Dataspaces The ``stride`` attribute contains a comma-separated list of integers. (In addition to the required comma delimiter, whitespace is also allowed to improve readability.) The number of items in the list is equal to the rank of the data being stored. The value of each item is the spacing of the data items in that subscript of the array. @type +++++ Defines the type of the element as allowed by NeXus. See :ref:`here` and :ref:`elsewhere` for the complete list of allowed types. @units ++++++ String describing the engineering units. The string should be appropriate for the value and should conform to the NeXus rules for units. Conformance is not validated at this time. attribute +++++++++ attributes to be used with this field dimensions ++++++++++ dimensions of a data element in a NeXus file enumeration +++++++++++ A field can specify which values are to be used .. Xpath = /xs:schema/xs:complexType[@name='choiceType'] .. index:: ! choiceType (NXDL data type) .. _NXDL.data.type.choiceType: choiceType ---------- A ``choice`` element is used when a named group might take one of several possible NeXus base classes. Logically, it must have at least two group children. Attributes of choiceType ++++++++++++++++++++++++ @name +++++ The name to be applied to the selected child group. None of the child groups should define a ``@name`` attribute. Elements of choiceType ++++++++++++++++++++++ group +++++ NeXus base class that could be used here. The group will take the ``@name`` attribute defined by the parent ``choice`` element so do not specify the ``@name`` attribute of the group here. .. Xpath = /xs:schema/xs:complexType[@name='groupType'] .. index:: ! groupType (NXDL data type) .. _NXDL.data.type.groupType: groupType --------- A group element refers to the definition of an existing NX object or a locally-defined component. Could contain these elements: * ``attribute`` * ``doc`` * ``field`` * ``group`` * ``link`` Note that a ``group`` element also includes the definitions of the ``basicComponent`` data type. (The ``groupType`` data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.) Attributes of groupType +++++++++++++++++++++++ @maxOccurs ++++++++++ Maximum number of times this ``group`` is allowed to be present within its parent ``group``. Note each ``group`` must have a ``name`` attribute that is unique among all ``group`` and ``field`` declarations within a common parent ``group``. @minOccurs ++++++++++ Minimum number of times this ``group`` is allowed to be present within its parent group. Note each ``group`` must have a ``name`` attribute that is unique among all ``group`` and ``field`` declarations within a common parent group. @name +++++ A particular scientific application may expect a name of a ``group`` element. It is helpful but not required to specify the ``name`` attribute in the NXDL file. It is suggested to always specify a ``name`` to avoid ambiguity. It is also suggested to derive the ``name`` from the type, using an additional number suffix as necessary. For example, consider a data file with only one ``NXentry``. The suggested default ``name`` would be ``entry``. For a data file with two or more ``NXentry`` groups, the suggested names would be ``entry1``, ``entry2``, ... Alternatively, a scientific application such as small-angle scattering might require a different naming procedure; two different ``NXaperture`` groups might be given the names ``beam_defining_slit`` and ``scatter_slit``. @optional +++++++++ A synonym for minOccurs=0. @recommended ++++++++++++ A synonym for optional, but with the recommendation that this ``group`` be specified. @type +++++ The ``type`` attribute *must* contain the name of a NeXus base class, application definition, or contributed definition. .. Xpath = /xs:schema/xs:complexType[@name='linkType'] .. index:: ! linkType (NXDL data type) .. _NXDL.data.type.linkType: linkType -------- A link to another item. Use a link to avoid needless repetition of information. (This data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.) @napimount ++++++++++ Group attribute that provides a URL to a group in another file. More information is described in the *NeXus Programmers Reference*. http://manual.nexusformat.org/_static/NeXusIntern.pdf @target +++++++ Declares the absolute HDF5 address of an existing field or group. The target attribute is added for NeXus to distinguish the HDF5 path to the original dataset. Could contain these elements: * ``doc`` Matching regular expression:: (/[a-zA-Z_][\w_]*(:[a-zA-Z_][\w_]*)?)+ For example, given a ``/entry/instrument/detector/polar_angle`` field, link it into the ``NXdata`` group (at ``/entry/data/polar_angle``). This would be the NeXus data file structure:: /: NeXus/HDF5 data file /entry:NXentry /data:NXdata /polar_angle:NX_NUMBER @target="/entry/instrument/detector/polar_angle" /instrument:NXinstrument /detector:NXdetector /polar_angle:NX_NUMBER @target="/entry/instrument/detector/polar_angle" .. Xpath = /xs:schema/xs:complexType[@name='symbolsType'] .. index:: ! symbolsType (NXDL data type) .. _NXDL.data.type.symbolsType: symbolsType ----------- Each ``symbol`` has a ``name`` and optional documentation. Please provide documentation that indicates what each symbol represents. For example:: number of reflecting surfaces number of wavelengths Elements of symbolsType +++++++++++++++++++++++ doc +++ Describe the purpose of this list of ``symbols``. This documentation will go into the manual. symbol ++++++ When multiple ``field`` elements share the same dimensions, such as the dimension scales associated with plottable data in an ``NXdata`` group, the length of each dimension written in a NeXus data file should be something that can be tested by the data file validation process. @name ~~~~~ Mnemonic variable name for this array index symbol. doc ~~~ Describe the purpose of the parent ``symbol``. This documentation will go into the manual. .. Xpath = /xs:schema/xs:complexType[@name='basicComponent'] .. index:: ! basicComponent (NXDL data type) .. _NXDL.data.type.basicComponent: basicComponent -------------- A ``basicComponent`` defines the allowed name format and attributes common to all ``field`` and ``group`` specifications. (This data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.) Attributes of basicComponent ++++++++++++++++++++++++++++ @name +++++ The ``name`` attribute is the identifier string for this entity. It is required that ``name`` must be unique within the enclosing ``group``. The name must match the regular expression defined by ``validItemName``. (Historical note: Originally, the rule (``validItemName``) was defined to allow only names that can be represented as valid variable names in most computer languages. ) Elements of basicComponent ++++++++++++++++++++++++++ doc +++ Describe this ``basicComponent`` and its use. This documentation will go into the manual. .. Xpath = /xs:schema/xs:simpleType[@name='validItemName'] .. index:: ! validItemName (NXDL data type) .. _NXDL.data.type.validItemName: validItemName ------------- Used for allowed names of elements and attributes. Note: No ``-`` characters (among others) are allowed and you cannot start or end with a period (``.``). HDF4 had a 64 character limit on names (possibly including NULL) and the NAPI enforces this via the ``NX_MAXNAMELEN`` variable with a **64** character limit (which may be 63 on a practical basis if one considers a NULL terminating byte). (This data type is used internally in the NXDL schema to define a data type.) NOTE: In some languages, it may be necessary to add a ``^`` at the start and a ``$`` at the end of the regular expression to constrain the match to an entire line. The value may be any ``xs:token`` that *also* matches the regular expression:: [a-zA-Z0-9_]([a-zA-Z0-9_.]*[a-zA-Z0-9_])? .. Xpath = /xs:schema/xs:simpleType[@name='validNXClassName'] .. index:: ! validNXClassName (NXDL data type) .. _NXDL.data.type.validNXClassName: validNXClassName ---------------- Used for allowed names of NX class types (e.g. NXdetector). Note this is *not* the instance name (e.g. ``bank1``) which is covered by ``validItemName``. (This data type is used internally in the NXDL schema to define a data type.) The value may be any ``nx:validItemName`` that *also* matches the regular expression:: NX.+ .. Xpath = /xs:schema/xs:simpleType[@name='validTargetName'] .. index:: ! validTargetName (NXDL data type) .. _NXDL.data.type.validTargetName: validTargetName --------------- This is a valid link target - currently it must be an absolute path made up of valid names with the ``/`` character delimiter. But we may want to consider allowing "``..``" (parent of directory) at some point. If the ``name`` attribute is helpful, then use it in the path with the syntax of *name:type* as in these examples:: /NXentry/NXinstrument/analyzer:NXcrystal/ef /NXentry/NXinstrument/monochromator:NXcrystal/ei /NX_other Must also consider use of ``name`` attribute in resolving ``link`` targets. (This data type is used internally in the NXDL schema to define a data type.) From the HDF5 documentation: *Note that relative path names in HDF5 do not employ the ``../`` notation, the UNIX notation indicating a parent directory, to indicate a parent group.* Thus, if we only consider the case of ``[name:]type``, the matching regular expression syntax is written: ``/[a-zA-Z_][\w_]*(:[a-zA-Z_][\w_]*)?)+``. Note that HDF5 also permits relative path names, such as: ``GroupA/GroupB/Dataset1`` but this is not permitted in the matching regular expression and not supported in NAPI. The value may be any ``xs:token`` that *also* matches the regular expression:: (/[a-zA-Z_][\w_]*(:[a-zA-Z_][\w_]*)?)+ .. Xpath = /xs:schema/xs:simpleType[@name='nonNegativeUnbounded'] .. index:: ! nonNegativeUnbounded (NXDL data type) .. _NXDL.data.type.nonNegativeUnbounded: nonNegativeUnbounded -------------------- A ``nonNegativeUnbounded`` allows values including all positive integers, zero, and the string ``unbounded``. (This data type is used internally in the NXDL schema to define a data type.) **The** ``xs:string`` **data type** The ``xs:string`` data type can contain characters, line feeds, carriage returns, and tab characters. See https://www.w3schools.com/xml/schema_dtypes_string.asp for more details. **The** ``xs:token`` **data type** The ``xs:string`` data type is derived from the ``xs:string`` data type. The ``xs:token`` data type also contains characters, but the XML processor will remove line feeds, carriage returns, tabs, leading and trailing spaces, and multiple spaces. See https://www.w3schools.com/xml/schema_dtypes_string.asp for more details.