@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.
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
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: choiceType
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
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
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.
{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
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
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
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
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: linkType
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
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.
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).
Is this attribute optional (if true) or required (if false)?
A synonym for optional, but with the recommendation that this attribute be specified.
Type of the attribute. For
group
specifications, the class name. Forfield
orattribute
specifications, the NXDL field type.
dimensions of an attribute with data value(s) in a NeXus file
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:
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.
NXDL
base
definitions define the dictionary of terms to use for these components. All terms in abase
definition are optional. NXDLapplication
definitions define what is required for a scientific interest. All terms in anapplication
definition are required. NXDLcontributed
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.
The
extends
attribute allows this definition to subclass from another NXDL, otherwiseextends="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 settingignoreExtraAttributes="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 settingignoreExtraFields="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 settingignoreExtraGroups="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 (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.
The
restricts
attribute is a flag to the data validation. Whenrestricts="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 therestricts
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.
Must be
type="group"
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, adefinition
may contain any of the items allowed in agroup
.
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.
Value could be either an unsigned integer or a symbol as defined in the symbol table of the NXDL file.
For example:
a[5]
hasrank="1"
whileb[8,5,6,4]
hasrank="4"
. See https://en.wikipedia.org/wiki/Rank_%28computer_programming%29 for more details.
Specify the parameters for each index of the
dimensions
element with adim
element. The number ofdim
entries should be equal to therank
of the array. For example, these terms describe a 2-D array with lengths (nsurf
,nwl
):1
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.
Deprecated: 2016-11-23 telco (https://github.com/nexusformat/definitions/issues/330)
The dimension specification is related to the
refindex
axis within theref
field by an offset ofincr
. Requiresref
andrefindex
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 arrayA[i,j,k]
,index="1"
would refer to thei
axis (subscript).
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 aspolar_angle
or../Qvec
or absolute path, such as/entry/path/to/follow/to/ref/field
.
Deprecated: 2016-11-23 telco (https://github.com/nexusformat/definitions/issues/330)
The dimension specification is the same as the
refindex
axis within theref
field. Requiresref
attribute to be present.
This dimension is required (true: default) or not required (false).
The default value is
true
.When
required="false"
is specified, all subsequent<dim
nodes (with higherindex
value) must also haverequired="false"
.
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:
Descriptive name of sample
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:
any
(This data type is used internally in the NXDL schema to define elements and attributes to be used by users in NXDL specifications.)
Note:
For documentation of definition
elements,
the first line of text in a doc
is used as a summary in the manual.
Follow the pattern as shown
in the base class NXDL files.
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:
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
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).
The value of
value
of anenumItem
is defined as an attribute rather than a name.
Individual items can be documented but this documentation might not be printed in the NeXus Reference Guide.
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.)
NOTE: Use of the
axes
attribute for a field is discouraged. It is for legacy support. You should use theaxes
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.
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 asignal
attribute.
The
stride
anddata_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.
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 pixelimage
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, usescalar
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
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
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.
This interprets the name attribute as: *
specified
= use as specified *any
= can be any name not already used in group
A synonym for minOccurs=0.
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.
A synonym for optional, but with the recommendation that this
field
be specified.
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 usesignal=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 anaxis
attribute.
The
stride
anddata_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 thestride
list determining how many elements to move in each dimension. Setting a value in thestride
array to 1 moves to each element in that dimension of the data array, while setting a value of 2 in a location in thestride
array moves to every other element in that dimension of the data array. A value in thestride
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.
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 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.
The name to be applied to the selected child group. None of the child groups should define a
@name
attribute.
NeXus base class that could be used here. The group will take the
@name
attribute defined by the parentchoice
element so do not specify the@name
attribute of the group here.
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.)
Maximum number of times this
group
is allowed to be present within its parentgroup
. Note eachgroup
must have aname
attribute that is unique among allgroup
andfield
declarations within a common parentgroup
.
Minimum number of times this
group
is allowed to be present within its parent group. Note eachgroup
must have aname
attribute that is unique among allgroup
andfield
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 thename
attribute in the NXDL file. It is suggested to always specify aname
to avoid ambiguity. It is also suggested to derive thename
from the type, using an additional number suffix as necessary. For example, consider a data file with only oneNXentry
. The suggested defaultname
would beentry
. For a data file with two or moreNXentry
groups, the suggested names would beentry1
,entry2
, … Alternatively, a scientific application such as small-angle scattering might require a different naming procedure; two differentNXaperture
groups might be given the namesbeam_defining_slit
andscatter_slit
.
A synonym for minOccurs=0.
A synonym for optional, but with the recommendation that this
group
be specified.
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.)
Group attribute that provides a URL to a group in another file. More information is described in the NeXus Programmers Reference.
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 theNXdata
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"
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
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 anNXdata
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
name
attribute is the identifier string for this entity. It is required thatname
must be unique within the enclosinggroup
. The name must match the regular expression defined byvalidItemName
. (Historical note: Originally, the rule (validItemName
) was defined to allow only 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.
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_])?
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.+
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_]*)?)+
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.)
xs:string
data typeThe 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.
xs:token
data typeThe 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.