2.3.1. Introduction to NeXus definitions¶
While the design principles of NeXus are explained in the NeXus: User Manual, this Reference Documentation specifies all allowed base classes and all standardized application definitions. Furthermore, it also contains contributed definitions of new bases classes or application definitions that are currently under review.
Base class definitions and application definitions have basically the same structure, but different semantics:
Base class definitions define the complete set of terms that might be used in an instance of that class.
Application definitions define the minimum set of terms that must be used in an instance of that class.
Base classes and application definitions are specified using a domain-specific XML scheme, the NXDL: The NeXus Definition Language.
2.3.1.1. Overview of NeXus definitions¶
For each class definition, the documentation is derived from content provided in the NXDL specification.
The documentation for each class consists of sections describing the Status, Description, table of Symbols (if defined), other NeXus base class Groups cited, an annotated Structure, and a link to the NXDL Source (XML) file.
Each of the NXDL files has its own tag in the version repository. Such as NXcrystal-1.0 is tagged in GiHub and accessible via URL: https://github.com/nexusformat/definitions/releases/tag/NXcrystal-1.0
2.3.1.1.1. Description¶
General documentation if this NXDL file.
2.3.1.1.2. Symbols table¶
The Symbols
table describes keywords used in this NXDL file to designate
array dimensions. For reasons of avoiding naming collisions and to facilitate
readbility and comprehension for those whom are new to an NXDL file, the following
guidelines are strongly encouraged:
All symbols used in the application definition are defined in a single
Symbols
table.The name of a symbol uses camel case without any white space or underscores.
examples:
nP: Total number of scan points
nE: Number of photon energies scanned
nFrames: Number of frames
detectorRank: Rank of data array provided by the detector for a single measurement
the
Symbols
table appears early in the .nxdl file above theNXentry
group
example from NXtomo.nxdl.xml
1<definition name="NXtomo" extends="NXobject" type="group"
2 category="application"
3 xmlns="http://definition.nexusformat.org/nxdl/3.1"
4 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
5 xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
6>
7 <symbols>
8 <doc>
9 These symbols will be used below to coordinate datasets with the same shape.
10 </doc>
11 <symbol name="nFrames">
12 <doc>Number of frames</doc>
13 </symbol>
14 <symbol name="xSize">
15 <doc>Number of pixels in X direction</doc>
16 </symbol>
17 <symbol name="ySize">
18 <doc>Number of pixels in Y direction</doc>
19 </symbol>
20 </symbols>
21 <doc>
22 This is the application definition for x-ray or neutron tomography raw data.
23
24 In tomography
25 a number of dark field images are measured, some bright field images and, of course the sample.
26 In order to distinguish between them images carry a image_key.
27 </doc>
28 <group type="NXentry" name="entry">
29 <field name="title" minOccurs="0" maxOccurs="1"/>
30...
2.3.1.1.3. Annotated Structure¶
A representation of the basic structure (groups, fields,
dimensions, attributes, and links) is prepared for each NXDL
specification. Indentation shows nested structure.
Attributes are prepended with the @
symbol.
Links use the characters ->
to represent the
path to the intended source of the information.
Indentation is used to indicate nesting of subgroups
(a feature common to application definitions).
Within each indentation level,
NeXus fields are listed first
in the order presented in the NXDL file, then
groups. Attributes
are listed after the documentation of each item and
are prefixed with the letter @
(do not use the
@
symbol in the actual attribute name).
The name of each item is in bold, followed by either
optional or required and then the NXDL base class
name (for groups) or the NeXus data type (for fields).
If units are to be provided with the field, the type of the
units is described, such as NX_DATE_TIME
.
NeXus Links (these specifications are typically present only in application definitions) are described by a local name, the text ->, then a suggested path to the source item to be linked to the local name.
2.3.1.1.4. Names (groups, fields, links, and attributes)¶
Name of the item.
Since name
needs to be restricted to valid
program variable names,
no “-
” characters can be allowed.
Name must satisfy both
HDF and XML
naming.
1 NameStartChar ::= _ | a..z | A..Z
2 NameChar ::= NameStartChar | 0..9
3 Name ::= NameStartChar (NameChar)*
4
5 Or, as a regular expression: [_a-zA-Z][_a-zA-Z0-9]*
6 equivalent regular expression: [_a-zA-Z][\w_]*
Attributes,
identified with a leading “at” symbol (@
)
and belong with the preceding field or group,
are additional metadata used to define this field or group.
In the example above, the
program_name
element has the
configuration
(optional) attribute while the
thumbnail
element has the
mime_type
(optional) attribute.
For groups, the name may not be declared in the NXDL specification. In such instances, the value shown in parentheses in the Name and Attributes column is a suggestion, obtained from the group by removing the “NX” prefix. See NXentry for examples.
When the name is allowed to be flexible (the exact name given
by this NXDL specification is not required but is set
at the time the HDF file is written), the flexible
part of the name will be written in all capital letters.
For example, in the NXdata group, the DATA
,
VARIABLE
, and VARIABLE_errors
fields are flexible.
2.3.1.1.5. NeXus data type¶
Type of data to be represented by this variable.
The type is one of those specified in NXDL: The NeXus Definition Language.
In the case where the variable can take only one value from a known
list, the list of known values is presented, such as in the
target_material
field above:
Ta | W | depleted_U | enriched_U | Hg | Pb | C
.
Selections with included whitespace are surrounded by quotes. See the
example above for usage.
For fields, the data type may not be specified in the NXDL file.
The default data type is NX_CHAR
.
See NXdata for examples.
2.3.1.1.6. Units¶
Data units, are given as character strings, must conform to the NeXus units standard. See the NeXus units section for details.
2.3.1.1.7. Description¶
A simple text description of the field. No markup or formatting is allowed.
NXDL element type |
minOccurs |
maxOccurs |
---|---|---|
group |
unbounded |
|
field |
unbounded |
|
attribute |
1 |
2.3.1.1.8. Choice¶
The choice
element allows one to create a group with a defined name
that is one specific NXDL base class from a defined list of possibilities
In some cases when creating an application definition, more than one
choice of base class might be used to define a particular subgroup.
For this particular situation, the choice
was added to the NeXus
NXDL Schema.
In this example fragment of an NXDL application definition,
the pixel_shape
could be represented by either
NXoff_geometry
or NXcylindrical_geometry
.
1 <choice name="pixel_shape">
2 <group type="NXoff_geometry">
3 <doc>
4 Shape description of each pixel. Use only if all pixels in the detector
5 are of uniform shape.
6 </doc>
7 </group>
8 <group type="NXcylindrical_geometry">
9 <doc>
10 Shape description of each pixel. Use only if all pixels in the detector
11 are of uniform shape and require being described by cylinders.
12 </doc>
13 </group>
14 </choice>
The @name
attribute of the choice
element specifies the name that
will appear in the HDF5 data file using one of the groups listed within the choice.
Thus, it is not necessary to specify the name in each group. (At some point,
the NXDL Schema may be modified to enforce this rule.)
A choice
element may be used wherever a group
element
is used. It must have at least two groups listed (otherwise, it would
not be useful).