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 <canSAS/2012-minimum.png>`)
See :ref:`below <NXcanSAS_minimum>` 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 <RegExpName>`.
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
.. 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.
.. 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.
Official canSAS group: **SASentry**
- For canSAS **SASdata**, this is always "I".
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).
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)`.
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`.
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.
ISO-8601 time [#iso8601]_
.. 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 <canSAS/Q-geometry.jpg>`)
: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.
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.
-
preferred
-
includes m2/m3 and 1/m/sr
-
includes cm2/cm3 and 1/cm/sr
-
includes m2/m3 and 1/m/sr
-
includes cm2/cm3 and 1/cm/sr
-
preferred
-
preferred
-
preferred
-
preferred
- For **SAStransmission_spectrum**, this is always "T".
-
the wavelengths field (as a dimension scale) corresponding to this transmission
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
====== ==============================================
ISO-8601 time [#iso8601]_
Wavelength of the radiation.
This array is of the same shape as ``T`` and ``Tdev``.
Transmission values (:math:`I/I_0`)
as a function of wavelength.
This array is of the same shape as ``lambda`` and ``Tdev``.
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"
.. 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``.