3.2. NXDL: The NeXus Definition Language
3.2.1.2. NXDL: Data Types and Units
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.
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: attributeType
Graphical representation of the NXDL attribute element
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: definition, definitionType, and definitionTypeAttr
Graphical representation of the NXDL definition element
The dimensions element describes the shape of an array. It is used only as a child of a field element.
For more details, see: dimensionsType
Graphical representation of the NXDL dimensions element
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: docType
Graphical representation of the NXDL doc element
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: enumerationType
Graphical representation of the NXDL enumeration element
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: fieldType
Graphical representation of the NXDL field element
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: groupType
Graphical representation of the NXDL group element
A link element can only be a child of a field or group element. It describes the path to the original source of the parent field or group.
For more details, see: linkType
Graphical representation of the NXDL link element
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: symbolsType
Graphical representation of the NXDL symbols element
Data 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.
Any new group or field may expect or require some common attributes.
(This data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.)
Name of the attribute (unique within the enclosing group).
Type of the attribute. For group specifications, the class name. For field or attribute specifications, the NXDL data type.
Description of this attribute. This documentation will go into the manual.
An enumeration specifies the values to be used.
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.
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:
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.)
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 <emphasis>must</emphasis> indicate their intended use, either as a base class or as an application definition.
The extends attribute allows this definition to subclass from another NXDL, otherwise extends="NXobject" should be used.
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!
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!
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!
The name of this NXDL file (without the file extensions). 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.
The restricts attribute is a flag to the data validation. When restricts="1", any non-standard component found (and checked for validity aginst 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.
(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. (Updated automatically, unlike the version attribute.)
Must be type="group"
Version of this NXDL definition. Each NXDL specification may have a different version to facilitate software maintenance. This value is modified by the person who edits this file when this NXDL specification has changed significantly (in a way that downstream software should be aware).
Use a symbols list to define each of the mnemonics that represent the length of each dimension in a vector or array.
In addition to an optional symbols list, a definition may contain any of the items allowed in a group.
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
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.)
Rank (number of dimensions) of the data structure. For example: a[5] has rank="1" while b[8,5,6,4] has rank="4". See http://en.wikipedia.org/wiki/Rank_(computer_programming) for more details.
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):
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.
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.
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.)
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.
The dimension specification is the same as the refindex axis within the ref field. Requires ref attribute to be present.
Integer length (number of values), or mnemonic symbol representing the length of this axis.
Documentation might be necessary to describe how the parts of the dimensions element are to be used.
NXDL allows for documentation on most elements using the doc element. The documentation is useful in several contexts. The documentation will be rendered in the manual. Documentation, is provided as tooltips by some XML editors when editing NXDL files. Simple documentation can be typed directly in the NXDL:
<field name="name">
<doc>Descriptive name of sample</doc>
</field>
This is suitable for basic descriptions that do not need extra formatting such as a bullet-list or a table. For more advanced control, use the rules of restructured text, such as in the NXdetector specification. Refer to examples in the NeXus base class NXDL files such as NXdata.
Could contain these elements:
(This data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.)
An enumeration restricts the values allowed for a specification. Each value is specified using an item element, such as: <item value="Synchrotron X-ray Source"/>. Could contain these elements:
(This data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.)
<field name="mode">
<doc>source operating mode</doc>
<enumeration>
<item value="Single Bunch"><doc>for storage rings</doc></item>
<item value="Multi Bunch"><doc>for storage rings</doc></item>
<!-- other sources could add to this -->
</enumeration>
</field>
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:
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.)
Presence of the axes attribute means this field is an ordinate.
This attribute contains a colon (or comma in legacy files) delimited list of the names of independent axes when plotting this field. Each name in this list must exist as a field in the same group. <!– perhaps even discourage use of square brackets in axes attribute? –> (Optionally, the list can be enclosed by square brackets but this is not common.) The regular expression for this rule is:
[A-Za-z_][\w_]*([ :][A-Za-z_][\w_]*)*
NOTE: Use of this attribute is discouraged. It is for legacy support. You should use the axes attribute instead.
Presence of the axis attribute means this field is an abcissa.
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 (abcissae) 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.
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:
- scaler = 0-D data to be plotted
- spectrum = 1-D data to be plotted
- image = 2-D data to be plotted
- vertex = 3-D data to be plotted
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.
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.
Defines the minimum number of times this element may be used. Its value is confined to zero or greater. Must be less than or equal to the value for the “maxOccurs” attribute. A value of “unbounded” is allowed.
The stride and 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 offset attribute determines the starting coordinates of the data array for each dimension.
See http://davis.lbl.gov/Manuals/HDF5-1.4.3/Tutor/phypereg.html or 4. Dataspace Selection Operations in http://www.hdfgroup.org/HDF5/doc1.6/Dataspaces.html.
The 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.
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 abcissa.
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.
The stride and 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 http://davis.lbl.gov/Manuals/HDF5-1.4.3/Tutor/phypereg.html or 4. Dataspace Selection Operations in http://www.hdfgroup.org/HDF5/doc1.6/Dataspaces.html.
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.
Defines the type of the element as allowed by the NAPI (NeXus Application Programmer Interface). See elsewhere for the complete list of allowed NAPI types.
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.
attributes to be used with this field
dimensions of a data element in a NeXus file
A field can specify which values are to be used
A group element refers to the definition of an existing NX object or a locally-defined component. Could contain these elements:
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.)
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.
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.
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.
The type attribute must contain the name of a NeXus base class, application definition, or contributed definition.
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.)
A link to another item, represented as an absolute path to an existing field such as /NXentry/NXinstrument/NXdetector/polar_angle. Could contain these elements:
- doc
Matching regular expression:
(/[a-zA-Z_][\w_]*(:[a-zA-Z_][\w_]*)?)+
Each symbol has a name and optional documentation. Please provide documentation that indicates what each symbol represents. For example:
<symbols>
<symbol name="nsurf"><doc>number of reflecting surfaces</doc></symbol>
<symbol name="nwl"><doc>number of wavelengths</doc></symbol>
</symbols>
Describe the purpose of this list of symbols. This documentation will go into the manual.
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.
Mnemonic variable name for this array index symbol.
Describe the purpose of the parent symbol. This documentation will go into the manual.
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.)
The presence of the deprecated attribute indicates to the data file validation process that an advisory message (specified as the content of the deprecated attribute) will be reported. Future versions of the NXDL file might not define (or even re-use) this component. For example:
deprecated="as of release MAJOR.MINOR"Note: because deprecated is an attribute, the XML rules do not permit it to have any element content.
The name attribute is the identifier string for this entity. It is required that name must be unique within the enclosing group. The rule (validItemName) is defined to only allow names that can be represented as valid variable names in most computer languages.
Describe this basicComponent and its use. This documentation will go into the manual.
Used for allowed names of elements and attributes. Need to be restricted to valid program variable names. Note: This means no “-” or ”.” characters can be allowed and you cannot start with a number. HDF4 had a 64 character limit on names (possibly including NULL) and NeXus 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.)
The value may be any xs:token that also matches the regular expression:
[A-Za-z_][\w_]*
Used for allowed names of NX class types (e.g. NXdetector) not the instance (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.+
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 (http://www.hdfgroup.org/HDF5/doc/UG/UG_frame09Groups.html):
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_]*)?)+
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 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 http://www.w3schools.com/Schema/schema_dtypes_string.asp for more details.