Permalink
Switch branches/tags
v2018.5 v3.3 v3.2 v3.1.0 Schema-3.4 Schema-3.3 NXxrot-1.0b NXxraylens-1.0 NXxnb-1.0b NXxlaueplate-1.0b NXxlaue-1.0b NXxkappa-1.0b NXxeuler-1.0b NXxbase-1.0b NXxasproc-1.0 NXxas-1.0 NXvelocity_selector-1.0 NXuser-1.0 NXtranslation-1.0 NXtransformations-1.0 NXtomoproc-1.0b NXtomophase-1.0b NXtomo-2.0 NXtofsingle-1.0b NXtofraw-1.0b NXtofnpd-1.0b NXtas-1.0b NXsubentry-1.0 NXstxm-1.1 NXsqom-1.0b NXspin_rotator-1.0 NXspecdata-1.0 NXspe-1.0 NXsource-1.0 NXsolenoid_magnet-1.0 NXsnshisto-1.0 NXsnsevent-1.0 NXslit-1.0 NXshape-1.0 NXseparator-1.0 NXsensor-1.0 NXscan-1.0b NXsastof-1.0b NXsas-1.0b NXsample_component-1.0 NXsample-1.0 NXroot-1.0 NXreftof-1.0b NXrefscan-1.0b NXreflections-1.1 NXreflections-1.0 NXquadrupole_magnet-1.0 NXprocess-1.0 NXpositioner-1.0 NXpolarizer-1.0 NXpinhole-1.0 NXparameters-1.0 NXorientation-1.0 NXobject-1.0 NXnote-1.0 NXmx-1.4 NXmonopd-1.0b NXmonochromator-1.0 NXmonitor-1.0 NXmoderator-1.0 NXmirror-1.0 NXmagnetic_kicker-1.0 NXlog-1.0 NXlauetof-1.0b NXiqproc-1.0b NXinstrument-1.0 NXinsertion_device-1.0 NXindirecttof-1.0b NXguide-1.0 NXgrating-1.0 NXgeometry-1.0 NXfresnel_zone_plate-1.0 NXfluo-1.0 NXflipper-1.0 NXfilter-1.0 NXfermi_chopper-1.0 NXevent_data-1.0 NXenvironment-1.0 NXentry-1.0 NXelectrostatic_kicker-1.0 NXdisk_chopper-1.0 NXdirecttof-1.0b NXdetector_module-1.0 NXdetector_group-1.0 NXdetector-1.1 NXdata-1.0 NXcrystal-1.0 NXcontainer-1.0 NXcollimator-1.0 NXcollection-1.0 NXcite-1.0 NXcharacterization-1.0 NXcapillary-1.0 NXcanSAS-1.0 NXbending_magnet-1.0
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
1287 lines (1079 sloc) 49.3 KB
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl" ?>
<!--
# NeXus - Neutron and X-ray Common Data Format
#
# Copyright (C) 2012-2018 NeXus International Advisory Committee (NIAC)
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 3 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# For further information, see http://www.nexusformat.org
-->
<!--
NOTE:
This NXDL refers to several image files (.jpg, .png) in its documentation.
All such related resources are stored in the related subdirectory: ./canSAS/
In general, for an NXDL file: NXsomenxdl.nxdl.xml
all related resources should be stored in subdirectory: ./somenxdl/
-->
<definition name="NXcanSAS" extends="NXobject" type="group"
category="application"
xmlns="http://definition.nexusformat.org/nxdl/3.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
>
<doc>
Implementation of the canSAS standard to store reduced small-angle scattering data of any dimension.
.. index:: canSAS
For more details, see:
* http://www.cansas.org/
* http://www.cansas.org/formats/canSAS1d/1.1/doc/
* http://cansas-org.github.io/canSAS2012/
* https://github.com/canSAS-org/NXcanSAS_examples
The minimum requirements for *reduced* small-angle scattering data
as described by canSAS are summarized in the following figure:
.. _canSAS_2012_minimum:
.. figure:: canSAS/2012-minimum.png
:width: 60%
The minimum requirements for *reduced* small-angle scattering data.
(:download:`full image &lt;canSAS/2012-minimum.png&gt;`)
See :ref:`below &lt;NXcanSAS_minimum&gt;` for the minimum required
information for a NeXus data file
written to the NXcanSAS specification.
.. rubric:: Implementation of canSAS standard in NeXus
This application definition is an implementation of the canSAS
standard for storing both one-dimensional and multi-dimensional
*reduced* small-angle scattering data.
* NXcanSAS is for reduced SAS data and metadata to be stored together in one file.
* *Reduced* SAS data consists of :math:`I(\vec{Q})` or :math:`I(|\vec{Q}|)`
* External file links are not to be used for the reduced data.
* A good practice/practise is, at least, to include a reference to how the data was acquired and processed. Yet this is not a requirement.
* There is no need for NXcanSAS to refer to any raw data.
The canSAS data format has a structure similar to NeXus, not identical.
To allow canSAS data to be expressed in NeXus, yet identifiable
by the canSAS standard, an additional group attribute ``canSAS_class``
was introduced. Here is the mapping of some common groups.
=============== ============ ==========================
group (*) NX_class canSAS_class
=============== ============ ==========================
sasentry NXentry SASentry
sasdata NXdata SASdata
sasdetector NXdetector SASdetector
sasinstrument NXinstrument SASinstrument
sasnote NXnote SASnote
sasprocess NXprocess SASprocess
sasprocessnote NXcollection SASprocessnote
sastransmission NXdata SAStransmission_spectrum
sassample NXsample SASsample
sassource NXsource SASsource
=============== ============ ==========================
(*) The name of each group is a suggestion,
not a fixed requirement and is chosen as fits each data file.
See the section on defining
:ref:`NXDL group and field names &lt;RegExpName&gt;`.
Refer to the NeXus Coordinate System drawing (:ref:`Design-CoordinateSystem`)
for choice and direction of :math:`x`, :math:`y`, and :math:`z` axes.
.. _NXcanSAS_minimum:
.. rubric:: The minimum required information for a NeXus data file
written to the NXcanSAS specification.
.. literalinclude:: canSAS/minimum-required.txt
:tab-width: 4
:linenos:
:language: text
</doc>
<group type="NXentry">
<attribute name="default" optional="true">
<doc>
.. index:: plotting
Declares which :ref:`NXdata` group
contains the data to be shown by default.
It is needed to resolve ambiguity when more than one :ref:`NXdata` group exists.
The value is the name of the default :ref:`NXdata` group.
Usually, this will be the name of the first *SASdata* group.
</doc>
</attribute>
<doc>
.. index:: NXcanSAS (applications); SASentry
Place the canSAS ``SASentry`` group as a child of a NeXus ``NXentry`` group
(when data from multiple techniques are being stored)
or as a replacement for the ``NXentry`` group.
Note: It is required for all numerical objects to provide
a *units* attribute that describes the engineering units.
Use the Unidata UDunits [#]_ specification
as this is compatible with various community standards.
.. [#] The UDunits specification also includes instructions for derived units.
</doc>
<attribute name="canSAS_class">
<doc>
Official canSAS group: **SASentry**
</doc>
<enumeration>
<item value="SASentry" />
</enumeration>
</attribute>
<attribute name="version">
<doc>
Describes the version of the canSAS standard used to write this data.
This must be a text (not numerical) representation. Such as::
@version="1.0"
</doc>
<enumeration>
<item value="1.0" />
</enumeration>
</attribute>
<field name="definition">
<doc>Official NeXus NXDL schema to which this subentry conforms.</doc>
<enumeration>
<item value="NXcanSAS" />
</enumeration>
</field>
<!--
============================
SASdata
============================
-->
<group type="NXdata">
<doc>
A *SASData* group contains a single reduced small-angle scattering data set
that can be represented as :math:`I(\vec{Q})` or :math:`I(|\vec{Q}|)`.
*Q* can be either a vector (:math:`\vec{Q}`) or a vector magnitude (:math:`|\vec{Q}|`)
The name of each *SASdata* group must be unique within a SASentry group.
Suggest using names such as ``sasdata01``.
NOTE: For the first *SASdata* group, be sure to write the chosen name
into the `SASentry/@default` attribute, as in::
SASentry/@default="sasdata01"
A *SASdata* group has several attributes:
* I_axes
* Q_indices
* Mask_indices
To indicate the dependency relationships of other varied parameters,
use attributes similar to ``@Mask_indices`` (such as ``@Temperature_indices``
or ``@Pressure_indices``).
</doc>
<attribute name="canSAS_class">
<doc>Official canSAS group: :index:`NXcanSAS (applications); SASdata`</doc>
<enumeration>
<item value="SASdata" />
</enumeration>
</attribute>
<!-- attributes, see: http://www.cansas.org/formats/canSAS2012/1.0/doc/framework.html#terms -->
<attribute name="signal" type="NX_CHAR" >
<doc>
Name of the default data field.
</doc>
<enumeration>
<item value="I"><doc>For canSAS **SASdata**, this is always "I".</doc></item>
</enumeration>
</attribute>
<attribute name="I_axes">
<doc>
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).
One entry is provided for every dimension of the ``I`` data object.
Such as::
@I_axes="Temperature", "Time", "Pressure", "Q", "Q"
Since there are five items in the list, the intensity field of this example
``I`` must be a five-dimensional array (rank=5).
</doc>
</attribute>
<attribute name="Q_indices" type="NX_INT">
<doc>
Integer or integer array that describes which indices
(of the :math:`I` data object) are used to
reference the ``Q`` data object. The items in this array
use zero-based indexing. Such as::
@Q_indices=1,3,4
which indicates that ``Q`` requires three indices
from the :math:`I` data object: one for time and
two for Q position. Thus, in this example, the
``Q`` data is time-dependent: :math:`\vec{Q}(t)`.
</doc>
</attribute>
<attribute name="mask" type="NX_CHAR" >
<doc>
Name of the data mask field.
.. see: https://github.com/nexusformat/definitions/issues/533
The data *mask* must have the same shape as the *data* field.
Positions in the mask correspond to positions in the *data* field.
The value of the mask field may be either a boolean array
where ``false`` means *no mask* and ``true`` means *mask*
or a more descriptive array as as defined in :ref:`NXdetector`.
</doc>
</attribute>
<attribute name="Mask_indices" optional="true">
<doc>
Integer or integer array that describes which indices
(of the :math:`I` data object) are used to
reference the ``Mask`` data object. The items in this
array use zero-based indexing. Such as::
@Mask_indices=3,4
which indicates that Q requires two indices
from the :math:`I` data object for Q position.
</doc>
</attribute>
<attribute name="timestamp" type="NX_DATE_TIME" optional="true">
<doc>
ISO-8601 time [#iso8601]_
</doc>
</attribute>
<field name="Q" type="NX_NUMBER" units="NX_PER_LENGTH">
<!-- http://www.cansas.org/formats/canSAS2012/1.0/doc/basics.html#definition-of -->
<doc>
.. index:: NXcanSAS (applications); Q
Array of :math:`Q` data to accompany :math:`I`.
.. figure:: canSAS/Q-geometry.jpg
:width: 60%
The :math:`\vec{Q}` geometry.
(:download:`full image &lt;canSAS/Q-geometry.jpg&gt;`)
:math:`Q` may be represented as either
the three-dimensional scattering vector :math:`\vec{Q}`
or the magnitude of the scattering vector, :math:`|\vec{Q}|`.
.. math:: |\vec{Q}| = (4\pi/\lambda) sin(\theta)
When we write :math:`Q`, we may refer to either or both of
:math:`|\vec{Q}|`
or :math:`\vec{Q}`, depending on the context.
</doc>
<attribute name="units" optional="false">
<doc>
Engineering units to use when expressing
:math:`Q` and related terms.
Data expressed in other units will generate
a warning from validation software and may not
be processed by some analysis software packages.
</doc>
<enumeration>
<item value="1/m" />
<item value="1/nm">
<doc>preferred</doc>
</item>
<item value="1/angstrom" />
</enumeration>
</attribute>
<attribute name="uncertainties" optional="true">
<doc>
(optional: for numerical arrays)
Names the dataset (in this SASdata group) that provides the
uncertainty to be used for data analysis.
The name of the dataset containing the :math:`Q` uncertainty
is flexible. The name must be unique in the *SASdata* group.
.. comment
see: https://github.com/canSAS-org/canSAS2012/issues/7
Such as::
@uncertainties="Q_uncertainties"
The *uncertainties* field will have the same *shape* (dimensions)
as the Q field.
These values are the estimates of uncertainty of each Q. By default,
this will be interpreted to be the estimated standard deviation.
In special cases, when a standard deviation cannot possibly be used,
its value can specify another measure of distribution width.
There may also be a subdirectory (optional) with constituent
components.
.. note:: To report distribution in reported :math:`Q` values,
use the ``@resolutions`` attribute. It is possible for both
``@resolutions`` and ``uncertainties`` to be reported.
</doc>
</attribute>
<attribute name="resolutions" type="NX_CHAR" optional="true">
<doc>
.. index:: NXcanSAS (applications); resolutions
(optional: for numerical arrays)
Names the dataset (in this SASdata group) containing the :math:`Q` resolution.
The name of the dataset containing the :math:`Q` resolution
is flexible. The name must be unique in the *SASdata* group.
.. comment
see: https://github.com/canSAS-org/canSAS2012/issues/7
The *resolutions* field will have the same *shape* (dimensions)
as the Q field.
Generally, this is the principal resolution of each :math:`Q`.
Names the data object (in this SASdata group) that provides the
:math:`Q` resolution to be used for data analysis. Such as::
@resolutions="Qdev"
To specify two-dimensional resolution for slit-smearing geometry,
such as (*dQw*, *dQl*), use a string array, such as::
@resolutions="dQw", "dQl"
There may also be a subdirectory (optional) with constituent
components.
This pattern will demonstrate how to introduce further as-yet
unanticipated terms related to the data.
.. comment
see: https://github.com/nexusformat/definitions/issues/492#issuecomment-262813907
By default, the values of the resolutions data object are assumed to be
one standard deviation of any function used to approximate the
resolution function. This equates to the width of the gaussian
distribution if a Gaussian is chosen. See the ``@resolutions_description``
attribute.
.. note:: To report uncertainty in reported :math:`Q` values,
use the ``@uncertainties`` attribute. It is possible for both
``@resolutions`` and ``uncertainties`` to be reported.
</doc>
</attribute>
<attribute name="resolutions_description" type="NX_CHAR" optional="true">
<doc>
(optional)
Generally, this describes the :math:`Q` ``@resolutions`` data object.
By default, the value is assumed to be "Gaussian". These are
suggestions:
* Gaussian
* Lorentzian
* Square :
note that the full width of the square would be ~2.9 times
the standard deviation specified in the vector
* Triangular
* Sawtooth-outward : vertical edge pointing to larger Q
* Sawtooth-inward vertical edge pointing to smaller Q
* Bin : range of values contributing
(for example, when 2-D detector data have been reduced
to a 1-D :math:`I(|Q|)` dataset)
For other meanings, it may be necessary to provide further details
such as the function used to assess the resolution.
In such cases, use additional datasets or a :ref:`NXnote` subgroup
to include that detail.
</doc>
</attribute>
</field>
<field name="I" type="NX_NUMBER">
<!-- http://www.cansas.org/formats/canSAS2012/1.0/doc/basics.html#definition-of-intensity -->
<doc>
.. index:: NXcanSAS (applications); I
Array of intensity (:math:`I`) data.
The intensity may be represented in one of these forms:
**absolute units**: :math:`d\Sigma/d\Omega(Q)`
differential cross-section
per unit volume per unit solid angle (such as: 1/cm/sr or 1/m/sr)
**absolute units**: :math:`d\sigma/d\Omega(Q)`
differential cross-section
per unit atom per unit solid angle (such as: cm^2 or m^2)
**arbitrary units**: :math:`I(Q)`
usually a ratio of two detectors
but units are meaningless (such as: a.u. or counts)
This presents a few problems
for analysis software to sort out when reading the data.
Fortunately, it is possible to analyze the *units* to determine which type of
intensity is being reported and make choices at the time the file is read. But this is
an area for consideration and possible improvement.
One problem arises with software that automatically converts data into some canonical
units used by that software. The software should not convert units between these different
types of intensity indiscriminately.
A second problem is that when arbitrary units are used, then the set of possible
analytical results is restricted. With such units, no meaningful volume fraction
or number density can be determined directly from :math:`I(Q)`.
In some cases, it is possible to apply a factor to convert the arbitrary
units to an absolute scale. This should be considered as a possibility
of the analysis process.
Where this documentation says *typical units*, it is possible that small-angle
data may be presented in other units and still be consistent with NeXus.
See the :ref:`design-units` section.
</doc>
<attribute name="units" optional="false">
<doc>
Engineering units to use when expressing
:math:`I` and intensity-related terms.
Data expressed in other units (or missing a ``@units`` attribute)
will be treated as ``arbitrary`` by some software packages.
For software using the UDUNITS-2 library, ``arbitrary`` will be
changed to ``unknown`` for handling with that library.
</doc>
<enumeration>
<item value="1/m">
<doc>includes m2/m3 and 1/m/sr</doc>
</item>
<item value="1/cm">
<doc>includes cm2/cm3 and 1/cm/sr</doc>
</item>
<item value="m2/g" />
<item value="cm2/g" />
<item value="arbitrary" />
</enumeration>
</attribute>
<attribute name="uncertainties" optional="true">
<doc>
(optional: for numerical arrays)
Names the dataset (in this SASdata group) that provides the
uncertainty of :math:`I` to be used for data analysis.
The name of the dataset containing the :math:`I` uncertainty
is flexible. The name must be unique in the *SASdata* group.
.. comment
see: https://github.com/canSAS-org/canSAS2012/issues/7
Generally, this is the estimate of the uncertainty of each :math:`I`.
Typically the estimated standard deviation.
*Idev* is the canonical name from the 1D standard.
The NXcanSAS standard allows for the name to be described using this attribute.
Such as::
@uncertainties="Idev"
</doc>
</attribute>
<attribute name="scaling_factor" optional="true">
<doc>
(optional)
Names the field (a.k.a. dataset) that contains a factor
to multiply ``I``. By default, this value is unity.
Should an uncertainty be associated with the scaling factor
field, the field containing that uncertainty would be
designated via the ``uncertainties`` attribute.
Such as::
I : NX_NUMBER
@uncertainties="Idev" : NX_CHAR
@scaling_factor="I_scaling" : NX_CHAR
Idev : NX_NUMBER
I_scaling : NX_NUMBER
@uncertainties="I_scaling_dev" : NX_CHAR
I_scaling_dev : NX_NUMBER
The exact names for ``I_scaling`` and ``I_scaling_dev`` are not
defined by NXcanSAS. The user has the flexibility to use names
different than those shown in this example.
</doc>
</attribute>
</field>
<field name="Idev" type="NX_NUMBER" minOccurs="0">
<doc>
.. index:: NXcanSAS (applications); Idev
Estimated **uncertainty** (usually standard deviation)
in :math:`I`. Must have the same units as :math:`I`.
When present, the name of this field is also
recorded in the *uncertainties* attribute of *I*, as in::
I/@uncertainties="Idev"
</doc>
<attribute name="units" optional="false">
<doc>
Engineering units to use when expressing
:math:`I` and intensity-related terms.
Data expressed in other units (or missing a ``@units`` attribute)
will generate a warning from any validation process
and will be treated as ``arbitrary`` by some analysis software packages.
For software using the UDUNITS-2 library, ``arbitrary`` will be
changed to ``unknown`` for handling with that library.
</doc>
<enumeration>
<item value="1/m">
<doc>includes m2/m3 and 1/m/sr</doc>
</item>
<item value="1/cm">
<doc>includes cm2/cm3 and 1/cm/sr</doc>
</item>
<item value="m2/g" />
<item value="cm2/g" />
<item value="arbitrary" />
</enumeration>
</attribute>
</field>
<field name="Qdev" type="NX_NUMBER" units="NX_PER_LENGTH" minOccurs="0">
<doc>
.. index:: NXcanSAS (applications); Qdev
Estimated :math:`Q` **resolution** (usually standard deviation).
Must have the same units as :math:`Q`.
When present, the name of this field is also
recorded in the *resolutions* attribute of *Q*,
as in::
Q/@resolutions="Qdev"
or::
Q/@resolutions="dQw", "dQl"
</doc>
<attribute name="units" optional="false">
<doc>
Engineering units to use when expressing
:math:`Q` and related terms.
Data expressed in other units may not be processed by some
software packages.
</doc>
<enumeration>
<item value="1/m" />
<item value="1/nm">
<doc>preferred</doc>
</item>
<item value="1/angstrom" />
</enumeration>
</attribute>
</field>
<field name="dQw" type="NX_NUMBER" units="NX_PER_LENGTH" minOccurs="0">
<doc>
.. index:: NXcanSAS (applications); dQw
:math:`Q` **resolution** along the axis of scanning
(the high-resolution *slit width* direction).
Useful for defining resolution data from
slit-smearing instruments such as Bonse-Hart geometry.
Must have the same units as :math:`Q`.
When present, the name of this field is also
recorded in the *resolutions* attribute of *Q*,
as in::
Q/@resolutions="dQw", "dQl"
</doc>
<attribute name="units" optional="false">
<doc>
Engineering units to use when expressing
:math:`Q` and related terms.
Data expressed in other units may not be processed by some
software packages.
</doc>
<enumeration>
<item value="1/m" />
<item value="1/nm">
<doc>preferred</doc>
</item>
<item value="1/angstrom" />
</enumeration>
</attribute>
</field>
<field name="dQl" type="NX_NUMBER" units="NX_PER_LENGTH" minOccurs="0">
<doc>
.. index:: NXcanSAS (applications); dQl
:math:`Q` **resolution** perpendicular to the axis of scanning
(the low-resolution *slit length* direction).
Useful for defining resolution data from
slit-smearing instruments such as Bonse-Hart geometry.
Must have the same units as :math:`Q`.
When present, the name of this field is also
recorded in the *resolutions* attribute of *Q*,
as in::
Q/@resolutions="dQw", "dQl"
</doc>
<attribute name="units" optional="false">
<doc>
Engineering units to use when expressing
:math:`Q` and related terms.
Data expressed in other units may not be processed by some
software packages.
</doc>
<enumeration>
<item value="1/m" />
<item value="1/nm">
<doc>preferred</doc>
</item>
<item value="1/angstrom" />
</enumeration>
</attribute>
</field>
<field name="Qmean" minOccurs="0" units="NX_PER_LENGTH" type="NX_NUMBER">
<doc>
Mean value of :math:`Q` for this data point.
Useful when describing data that has been
binned from higher-resolution data.
It is expected that ``Q`` is provided
and that both ``Q`` and ``Qmean`` will have the same units.
</doc>
<attribute name="units" optional="false">
<doc>
Engineering units to use when expressing
:math:`Q` and related terms.
Data expressed in other units may not be processed by some
software packages.
</doc>
<enumeration>
<item value="1/m" />
<item value="1/nm">
<doc>preferred</doc>
</item>
<item value="1/angstrom" />
</enumeration>
</attribute>
</field>
<field name="ShadowFactor" minOccurs="0" units="NX_DIMENSIONLESS">
<doc>
A numerical factor applied to pixels affected by the beam stop penumbra.
Used in data files from NIST/NCNR instruments.
See: J.G. Barker and J.S. Pedersen (1995) *J. Appl. Cryst.* **28**, 105-114.
</doc>
</field>
</group>
<!-- optional items -->
<field name="title" minOccurs="1" maxOccurs="1">
<doc>
Title of this *SASentry*.
Make it so that you can recognize the data by its title.
Could be the name of the sample,
the name for the measured data, or something else representative.
</doc>
</field>
<field name="run" minOccurs="1" maxOccurs="unbounded" nameType="any">
<doc>
Run identification for this *SASentry*.
For many facilities, this is an integer, such as en experiment number.
Use multiple instances of ``run`` as needed, keeping
in mind that HDF5 requires unique names for all entities
in a group.
</doc>
<attribute name="name" optional="true">
<doc>
Optional string attribute to identify this particular *run*.
Could use this to associate (correlate) multiple *SASdata* elements with *run* elements.
</doc>
</attribute>
</field>
<group type="NXinstrument" minOccurs="0">
<attribute name="canSAS_class">
<doc>Official canSAS group: :index:`NXcanSAS (applications); SASinstrument`</doc>
<enumeration>
<item value="SASinstrument" />
</enumeration>
</attribute>
<doc>
Description of the small-angle scattering instrument.
Consider, carefully, the relevance to the SAS data analysis process
when adding subgroups in this **NXinstrument** group. Additional information
can be added but will likely be ignored by standardized data anlysis processes.
The NeXus :ref:`NXbeam` base class may be added as a subgroup of this **NXinstrument**
group *or* as a subgroup of the **NXsample** group to describe properties of the beam at any
point downstream from the source.
</doc>
<!--
===========
SASaperture
===========
-->
<group type="NXaperture" minOccurs="0">
<doc>
:ref:`NXaperture` is generic and limits the variation in data files.
Possible NeXus base class alternatives are: :ref:`NXpinhole` or :ref:`NXslit`.
</doc>
<attribute name="canSAS_class">
<doc>Official canSAS group: :index:`NXcanSAS (applications); SASaperture`</doc>
<enumeration>
<item value="SASaperture" />
</enumeration>
</attribute>
<field name="shape">
<doc>
describe the type of aperture (pinhole, 4-blade slit, Soller slit, ...)
</doc>
</field>
<field name="x_gap" type="NX_NUMBER" units="NX_LENGTH" minOccurs="0" maxOccurs="1">
<doc>opening along the :math:`x` axis</doc>
</field>
<field name="y_gap" type="NX_NUMBER" units="NX_LENGTH" minOccurs="0" maxOccurs="1">
<doc>opening along the :math:`y` axis</doc>
</field>
</group>
<!--
==============
SAScollimation
==============
-->
<group type="NXcollimator" minOccurs="0">
<attribute name="canSAS_class">
<doc>Official canSAS group: :index:`NXcanSAS (applications); SAScollimation`</doc>
<enumeration>
<item value="SAScollimation" />
</enumeration>
</attribute>
<doc>
Description of a collimating element (defines the divergence of the beam) in the instrument.
To document a slit, pinhole, or the beam, refer to the
documentation of the ``NXinstrument`` group above.
</doc>
<field name="length" type="NX_NUMBER" units="NX_LENGTH" minOccurs="0" maxOccurs="1">
<doc>Amount/length of collimation inserted (as on a SANS instrument)</doc>
</field>
<field name="distance" type="NX_NUMBER" units="NX_LENGTH" minOccurs="0" maxOccurs="1">
<doc>Distance from this collimation element to the sample</doc>
</field>
<!-- SAScollimation -->
</group>
<!--
============================
SASdetector
============================
-->
<group type="NXdetector" minOccurs="0">
<attribute name="canSAS_class">
<doc>Official canSAS group: :index:`NXcanSAS (applications); SASdetector`</doc>
<enumeration>
<item value="SASdetector" />
</enumeration>
</attribute>
<doc>
Description of a detector in the instrument.
</doc>
<field name="name" maxOccurs="1">
<doc>Identifies the name of this detector</doc>
</field>
<field name="SDD" type="NX_NUMBER" units="NX_LENGTH" minOccurs="0" maxOccurs="1">
<doc>
Distance between sample and detector.
Note: In NXdetector, the ``distance`` field records the
distance to the previous component ... most often the sample.
This use is the same as ``SDD`` for most SAS
instruments but not all. For example, Bonse-Hart cameras
have one or more crystals between the sample and detector.
We define here the field ``SDD`` to document without
ambiguity the distance between sample and detector.
</doc>
</field>
<field name="slit_length" type="NX_NUMBER" units="NX_PER_LENGTH" minOccurs="0" maxOccurs="1">
<doc>
Slit length of the instrument for this detector,
expressed in the same units as :math:`Q`.
</doc>
</field>
<field name="x_position" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_LENGTH">
<doc>Location of the detector in :math:`x`</doc>
</field>
<field name="y_position" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_LENGTH">
<doc>Location of the detector in :math:`y`</doc>
</field>
<field name="roll" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_ANGLE">
<doc>Rotation of the detector about the :math:`z` axis (roll)</doc>
</field>
<field name="pitch" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_ANGLE">
<doc>Rotation of the detector about the :math:`x` axis (roll)</doc>
</field>
<field name="yaw" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_ANGLE">
<doc>Rotation of the detector about the :math:`y` axis (yaw)</doc>
</field>
<field name="beam_center_x" type="NX_FLOAT" units="NX_LENGTH" minOccurs="0" maxOccurs="1">
<doc>
Position of the beam center on the detector.
This is the x position where the direct beam would hit the detector plane.
This is a length and can be outside of the actual
detector. The length can be in physical units or pixels
as documented by the units attribute. The value can be any
real number (positive, zero, or negative).
</doc>
</field>
<field name="beam_center_y" type="NX_FLOAT" units="NX_LENGTH" minOccurs="0" maxOccurs="1">
<doc>
Position of the beam center on the detector.
This is the y position where the direct beam would hit the detector plane.
This is a length and can be outside of the actual
detector. The length can be in physical units or pixels
as documented by the units attribute. The value can be any
real number (positive, zero, or negative).
</doc>
</field>
<field name="x_pixel_size" type="NX_FLOAT" units="NX_LENGTH" minOccurs="0" maxOccurs="1">
<doc>Size of each detector pixel. If it is scalar all pixels are the same size</doc>
</field>
<field name="y_pixel_size" type="NX_FLOAT" units="NX_LENGTH" minOccurs="0" maxOccurs="1">
<doc>Size of each detector pixel. If it is scalar all pixels are the same size</doc>
</field>
<!-- SASdetector -->
</group>
<!--
============================
SASsource
============================
-->
<group type="NXsource" minOccurs="0">
<attribute name="canSAS_class">
<doc>Official canSAS group: :index:`NXcanSAS (applications); SASsource`</doc>
<enumeration>
<item value="SASsource" />
</enumeration>
</attribute>
<doc>
Description of the radiation source.
</doc>
<field name="radiation" maxOccurs="1">
<doc>
Name of the radiation used.
Note that this is **not** the name of the facility!
</doc>
<enumeration>
<!-- enumeration values from NXsource/type and NXsource/probe -->
<item value="Spallation Neutron Source" />
<item value="Pulsed Reactor Neutron Source" />
<item value="Reactor Neutron Source" />
<item value="Synchrotron X-ray Source" />
<item value="Pulsed Muon Source" />
<item value="Rotating Anode X-ray" />
<item value="Fixed Tube X-ray" />
<item value="UV Laser" />
<item value="Free-Electron Laser" />
<item value="Optical Laser" />
<item value="Ion Source" />
<item value="UV Plasma Source" />
<item value="neutron" />
<item value="x-ray" />
<item value="muon" />
<item value="electron" />
<item value="ultraviolet" />
<item value="visible light" />
<item value="positron" />
<item value="proton" />
</enumeration>
</field>
<field name="beam_shape" minOccurs="0" maxOccurs="1">
<doc>Text description of the shape of the beam (incident on the sample).</doc>
</field>
<field name="incident_wavelength" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_WAVELENGTH">
<doc>wavelength (:math:`\lambda`) of radiation incident on the sample</doc>
</field>
<field name="wavelength_min" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_WAVELENGTH">
<doc>
Some facilities specify wavelength using a range.
This is the lowest wavelength in such a range.
</doc>
</field>
<field name="wavelength_max" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_WAVELENGTH">
<doc>
Some facilities specify wavelength using a range.
This is the highest wavelength in such a range.
</doc>
</field>
<field name="incident_wavelength_spread" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_WAVELENGTH">
<doc>
Some facilities specify wavelength using a range.
This is the width (FWHM) of such a range.
</doc>
</field>
<field name="beam_size_x" type="NX_NUMBER" units="NX_LENGTH" minOccurs="0" maxOccurs="1">
<doc>Size of the incident beam along the x axis.</doc>
</field>
<field name="beam_size_y" type="NX_NUMBER" units="NX_LENGTH" minOccurs="0" maxOccurs="1">
<doc>Size of the incident beam along the y axis.</doc>
</field>
<!-- SASsource -->
</group>
<!-- SASinstrument -->
</group>
<!--
==============
SASsample
==============
-->
<group type="NXsample" minOccurs="0">
<attribute name="canSAS_class">
<doc>Official canSAS group: :index:`NXcanSAS (applications); SASsample`</doc>
<enumeration>
<item value="SASsample" />
</enumeration>
</attribute>
<doc>
Description of the sample.
</doc>
<field name="name" maxOccurs="1">
<doc>**ID**: Text string that identifies this sample.</doc>
</field>
<field name="thickness" type="NX_FLOAT" minOccurs="0" maxOccurs="1" units="NX_LENGTH">
<doc>Thickness of this sample</doc>
</field>
<field name="transmission" type="NX_NUMBER" minOccurs="0" maxOccurs="1" units="NX_DIMENSIONLESS">
<doc>
Transmission (:math:`I/I_0`) of this sample.
There is no *units* attribute as this number is dimensionless.
Note: the ability to store a transmission *spectrum*,
instead of a single value, is provided elsewhere in the structure,
in the *SAStransmission_spectrum* element.
</doc>
</field>
<field name="temperature" type="NX_NUMBER" minOccurs="0" maxOccurs="1" units="NX_TEMPERATURE">
<doc>Temperature of this sample.</doc>
</field>
<field name="details" minOccurs="0" maxOccurs="unbounded" nameType="any">
<doc>Any additional sample details.</doc>
</field>
<field name="x_position" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_LENGTH">
<doc>Location of the sample in :math:`x`</doc>
</field>
<field name="y_position" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_LENGTH">
<doc>Location of the sample in :math:`y`</doc>
</field>
<field name="roll" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_ANGLE">
<doc>Rotation of the sample about the :math:`z` axis (roll)</doc>
</field>
<field name="pitch" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_ANGLE">
<doc>Rotation of the sample about the :math:`x` axis (roll)</doc>
</field>
<field name="yaw" minOccurs="0" maxOccurs="1" type="NX_NUMBER" units="NX_ANGLE">
<doc>Rotation of the sample about the :math:`y` axis (yaw)</doc>
</field>
<!-- NXsample -->
</group>
<!--
==============
SASprocess
==============
-->
<group type="NXprocess" minOccurs="0" maxOccurs="unbounded">
<attribute name="canSAS_class">
<doc>Official canSAS group: :index:`NXcanSAS (applications); SASprocess`</doc>
<enumeration>
<item value="SASprocess" />
</enumeration>
</attribute>
<doc>
Description of a processing or analysis step.
Add additional fields as needed to describe value(s) of any
variable, parameter, or term related to the *SASprocess* step.
Be sure to include *units* attributes for all numerical fields.
</doc>
<field name="name" minOccurs="0" maxOccurs="1">
<doc>Optional name for this data processing or analysis step</doc>
</field>
<field name="date" type="NX_DATE_TIME" minOccurs="0" maxOccurs="1">
<doc>
Optional date for this data processing or analysis step. [#iso8601]_
.. [#iso8601] ISO-8601 standard time representation.
NeXus dates and times are reported in ISO-8601
(e.g., ``yyyy-mm-ddThh:mm:ss``)
or modified ISO-8601 (e.g., ``yyyy-mm-dd hh:mm:ss``).
See: http://www.w3.org/TR/NOTE-datetime
or http://en.wikipedia.org/wiki/ISO_8601 for more details.
</doc>
</field>
<field name="description" minOccurs="0" maxOccurs="1">
<doc>Optional description for this data processing or analysis step</doc>
</field>
<field name="term" minOccurs="0" maxOccurs="unbounded" nameType="any">
<doc>
Specifies the value of a single variable, parameter,
or term (while defined here as a string, it could be a number)
related to the *SASprocess* step.
Note:
The name *term* is not required, it could take any name,
as long as the name is unique within this group.
</doc>
</field>
<!--
suggested at NIAC2014
Isn't this ALWAYS a possibility in any NeXus base class?
Not needed to define this but it is a good suggestion for usage.
-->
<group type="NXnote" minOccurs="0" maxOccurs="unbounded">
<doc>
Any additional notes or subprocessing steps will be documented here.
An **NXnote** group can be added to any NeXus group at or below the
**NXentry** group. It is shown here as a suggestion of a good place
to *consider* its use.
</doc>
</group>
<group type="NXcollection" minOccurs="0" maxOccurs="unbounded">
<doc>
Describes anything about *SASprocess* that is not already described.
Any content not defined in the canSAS standard can be placed at this point.
Note:
The name of this group is flexible, it could take any name,
as long as it is unique within the **NXprocess** group.
</doc>
<attribute name="canSAS_class">
<doc>
Official canSAS group: :index:`NXcanSAS (applications); SASprocessnote`
</doc>
<enumeration>
<item value="SASprocessnote" />
</enumeration>
</attribute>
<!-- SASprocessnote -->
</group>
<!-- SASprocess -->
</group>
<!--
==============
SASnote
==============
-->
<group type="NXcollection" minOccurs="0" maxOccurs="unbounded">
<attribute name="canSAS_class">
<doc>
Official canSAS group: :index:`NXcanSAS (applications); SASnote`
</doc>
<enumeration>
<item value="SASnote" />
</enumeration>
</attribute>
<doc>
Free form description of anything not covered by other elements.
</doc>
</group>
<!--
============================
SAStransmission_spectrum
============================
-->
<group type="NXdata" minOccurs="0">
<doc>
The *SAStransmission_spectrum* element
This describes certain data obtained from a variable-wavelength source
such as pulsed-neutron source.
<!-- requested to be in the 1D format by ISIS -->
The name of each *SAStransmission_spectrum* group must be unique within a SASentry group.
Suggest using names such as ``sastransmission_spectrum01``.
</doc>
<attribute name="canSAS_class">
<doc>Official canSAS group: :index:`NXcanSAS (applications); SAStransmission_spectrum`</doc>
<enumeration>
<item value="SAStransmission_spectrum" />
</enumeration>
</attribute>
<attribute name="signal" type="NX_CHAR" >
<doc>
Name of the default data field.
</doc>
<enumeration>
<item value="T"><doc>For **SAStransmission_spectrum**, this is always "T".</doc></item>
</enumeration>
</attribute>
<attribute name="T_axes">
<enumeration>
<item value="T">
<doc>the wavelengths field (as a dimension scale) corresponding to this transmission</doc>
</item>
</enumeration>
</attribute>
<attribute name="name">
<doc>
Identify what type of spectrum is being described.
It is expected that this value will take either of these two values:
====== ==============================================
value meaning
====== ==============================================
sample measurement with the sample and container
can measurement with just the container
====== ==============================================
</doc>
</attribute>
<attribute name="timestamp" type="NX_DATE_TIME" optional="true">
<doc>
ISO-8601 time [#iso8601]_
</doc>
</attribute>
<field name="lambda" type="NX_NUMBER" units="NX_WAVELENGTH">
<doc>
Wavelength of the radiation.
This array is of the same shape as ``T`` and ``Tdev``.
</doc>
</field>
<field name="T" type="NX_NUMBER" units="NX_DIMENSIONLESS">
<doc>
Transmission values (:math:`I/I_0`)
as a function of wavelength.
This array is of the same shape as ``lambda`` and ``Tdev``.
</doc>
<attribute name="uncertainties">
<doc>
Names the dataset (in this SASdata group) that provides the
uncertainty of each transmission :math:`T` to be used for data analysis.
The name of the dataset containing the :math:`T` uncertainty
is expected to be ``Tdev``.
.. comment
see: https://github.com/canSAS-org/canSAS2012/issues/7
Typically:
@uncertainties="Tdev"
</doc>
</attribute>
</field>
<field name="Tdev" type="NX_NUMBER" units="NX_DIMENSIONLESS" >
<doc>
.. index:: NXcanSAS (applications); Tdev
Estimated uncertainty (usually standard deviation)
in :math:`T`. Must have the same units as :math:`T`.
This is the field is named in the *uncertainties* attribute of *T*, as in::
T/@uncertainties="Tdev"
This array is of the same shape as ``lambda`` and ``T``.
</doc>
</field>
</group>
</group>
</definition>