.. auto-generated by script ../../../../utils/nxdl2rst.py from the NXDL source ../../../../contributed_definitions/NXcanSAS.nxdl.xml .. index:: ! NXcanSAS (contributed definition) ! canSAS (contributed definition) see: canSAS (contributed definition); NXcanSAS .. _NXcanSAS: ======== NXcanSAS ======== **Status**: contributed definition, extends :ref:`NXobject`, version 1.0 **Description**: Implementation of the :index:`canSAS` standard to store reduced multi-dimensional small-angle scattering data. for more details, see: * http://www.cansas.org/ * http://www.cansas.org/formats/canSAS2012/1.0/doc **Symbols**: No symbol table **Groups cited**: :ref:`NXcollection`, :ref:`NXcollimator`, :ref:`NXdata`, :ref:`NXdetector`, :ref:`NXinstrument`, :ref:`NXorientation`, :ref:`NXparameters`, :ref:`NXprocess`, :ref:`NXsample`, :ref:`NXsource`, :ref:`NXsubentry`, :ref:`NXtranslation` .. index:: NXsubentry (base class); used in contributed definition, NXdata (base class); used in contributed definition, NXparameters (base class); used in contributed definition, NXinstrument (base class); used in contributed definition, NXcollimator (base class); used in contributed definition, NXdetector (base class); used in contributed definition, NXsource (base class); used in contributed definition, NXsample (base class); used in contributed definition, NXtranslation (base class); used in contributed definition, NXorientation (base class); used in contributed definition, NXprocess (base class); used in contributed definition, NXcollection (base class); used in contributed definition **Structure**: **(subentry)**: :ref:`NXsubentry` .. index:: NXcanSAS (contributed definition); SASentry Place the canSAS ``SASentry`` group as a child of a NeXus ``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. .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` Official canSAS group: **SASentry** Obligatory value: ``SASentry`` .. index:: version (attribute) **@version**: :ref:`NX_CHAR ` 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" Obligatory value: ``1.0`` .. index:: definition (data field) **definition**: :ref:`NX_CHAR ` Official NeXus NXDL schema to which this subentry conforms. Obligatory value: ``NXcanSAS`` .. index:: title (data field) **title**: :ref:`NX_CHAR ` Title of this *SASentry*. .. index:: run (data field) **run**: :ref:`NX_CHAR ` Run identification for this *SASentry*. For many facilities, this is an integer. Use multiple instances of ``run`` as needed. .. index:: name (attribute) **@name**: :ref:`NX_CHAR ` Optional string attribute to identify this particular *run*. Could use this to associate (correlate) multiple *SASdata* elements with *run* elements. **(data)**: :ref:`NXdata` A *SASData* group contains reduced a single small-angle scattering data set that can be represented as :math:`I(\vec{Q})` or :math:`I(|\vec{Q}|)`. .. figure:: ../../../../contributed_definitions/SASdata.png :width: 60% The *SASdata* element *Q* can be either a vector (:math:`\vec{Q}`) or a vector magnitude (:math:`|\vec{Q}|`) The name of each *SASdata* must be unique within a SASentry group. Such as ``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``). .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` Official canSAS group: :index:`NXcanSAS (contributed definition); SASdata` Obligatory value: ``SASdata`` .. index:: I_axes (attribute) **@I_axes**: :ref:`NX_CHAR ` Comma-separated list that describes the names of the data objects that correspond to the indices 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 ``I`` must be a five-dimensional array (rank=5). .. index:: Q_indices (attribute) **@Q_indices**: :ref:`NX_CHAR ` 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)`. .. index:: Mask_indices (attribute) **@Mask_indices**: :ref:`NX_CHAR ` 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. .. index:: Q (data field) **Q**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_PER_LENGTH `} .. index:: NXcanSAS (contributed definition); Q Array of :math:`Q` data to accompany :math:`I`. .. figure:: ../../../../contributed_definitions/canSAS-Q-geometry.jpg :width: 60% The :math:`\vec{Q}` geometry. :math:`Q` may be represented either as the three-dimensional scattering vector :math:`\vec{Q}` or by 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. .. index:: uncertainty (attribute) **@uncertainty**: :ref:`NX_CHAR ` Typically the estimated standard deviation. More general, this is the estimate of the uncertainty of each "math:`Q`. Can use this to describe the slit-length at each datum. Use a subgroup to describe any supplementary uncertainty data such as two-dimensional. (optional for numerical arrays) Name of the data object (in this SASdata group) that provides the uncertainty to be used for data analysis. .. index:: I (data field) **I**: :ref:`NX_NUMBER ` .. index:: NXcanSAS (contributed definition); 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 (typical units: 1/cm/sr) **absolute units**: :math:`d\sigma/d\Omega(Q)` differential cross-section per unit atom per unit solid angle (typical units: cm^2) **arbitrary units**: :math:`I(Q)` usually a ratio of two detectors but units are meaningless (typical units: a.u.) 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. .. index:: uncertainty (attribute) **@uncertainty**: :ref:`NX_CHAR ` Typically the estimated standard deviation. :math:`1/\sqrt{I}` for Poisson statistics. More generally, though, this is the estimate of the uncertainty of each "math:`I`. (optional for numerical arrays) Name of the data object (in this SASdata group) that provides the uncertainty to be used for data analysis. *Idev* is the canonical name from the 1D standard. The multi-D standard allows for this name to be described in this attribute. .. index:: Qmean (data field) **Qmean**: :ref:`NX_CHAR ` {units=\ :ref:`NX_PER_LENGTH `} Mean value of :math:`Q` for this data point. Useful when describing data that has been binned from higher-resolution data. It is unexpected for ``Q`` and ``Qmean`` to have different units. .. index:: ShadowFactor (data field) **ShadowFactor**: :ref:`NX_CHAR ` {units=\ :ref:`NX_DIMENSIONLESS `} 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. **(parameters)**: :ref:`NXparameters` Supplementary Uncertainty Data .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` ad hoc canSAS group: :index:`NXcanSAS (contributed definition); SASuncertainties` Obligatory value: ``SASuncertainties`` **(instrument)**: :ref:`NXinstrument` This the SAS instrument. .. figure:: ../../../../contributed_definitions/SASinstrument.png :width: 60% The *SASinstrument* element .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` Official canSAS group: :index:`NXcanSAS (contributed definition); SASinstrument` Obligatory value: ``SASinstrument`` **(collimator)**: :ref:`NXcollimator` Description of a collimating element in the instrument. .. figure:: ../../../../contributed_definitions/SAScollimation.png :width: 60% The *SAScollimation* element .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` Official canSAS group: :index:`NXcanSAS (contributed definition); SAScollimation` Obligatory value: ``SAScollimation`` .. index:: length (data field) **length**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} Amount/length of collimation inserted (as on a SANS instrument) **aperture**: :ref:`NXparameters` Description of a slit or aperture. .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` *ad hoc* canSAS_class. Obligatory value: ``container`` .. index:: name (attribute) **@name**: :ref:`NX_CHAR ` Optional name attribute for this aperture .. index:: type (attribute) **@type**: :ref:`NX_CHAR ` Optional text attribute to describe the type of aperture (pinhole, 4-blade slit, Soller slit, ...). .. index:: distance (data field) **distance**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} Distance from this collimation element to the sample. **size**: :ref:`NXparameters` Opening dimensions of this aperture. .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` *ad hoc* canSAS_class. Obligatory value: ``container`` .. index:: x (data field) **x**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} Dimension of the collimation in :math:`x`. .. index:: y (data field) **y**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} Dimension of the collimation in :math:`y`. .. index:: z (data field) **z**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} Dimension of the collimation in :math:`z`. While :math:`z` is allowed by the canSAS standard, it may not make sense to use it in some situations. Use of :math:`z` may be ignored by processing software. **(detector)**: :ref:`NXdetector` Description of a detector in the instrument. .. figure:: ../../../../contributed_definitions/SASdetector.png :width: 60% The *SASdetector* element .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` Official canSAS group: :index:`NXcanSAS (contributed definition); SASdetector` Obligatory value: ``SASdetector`` .. index:: name (data field) **name**: :ref:`NX_CHAR ` Identifies the name of this detector .. index:: SDD (data field) **SDD**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} Distance between sample and detector. .. index:: slit_length (data field) **slit_length**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_PER_LENGTH `} Slit length of the instrument for this detector, expressed in the same units as :math:`Q`. **offset**: :ref:`NXparameters` Offset of the detector position. .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` *ad hoc* canSAS_class. Obligatory value: ``container`` .. index:: x (data field) **x**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} .. index:: y (data field) **y**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} .. index:: z (data field) **z**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} While :math:`z` is allowed by the canSAS standard, it may not make sense to use it in some situations. Use of :math:`z` may be ignored by processing software. **orientation**: :ref:`NXparameters` The orientation element describes simple rotations about a single axis (rather than a full set of rotations as in a crystallographic context). .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` *ad hoc* canSAS_class. Obligatory value: ``container`` .. index:: roll (data field) **roll**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} Roll is rotation about the :math:`z` axis. .. index:: pitch (data field) **pitch**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} Pitch is rotation about the :math:`x` axis. .. index:: yaw (data field) **yaw**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} Yaw is rotation about the :math:`y` axis. **beam_center**: :ref:`NXparameters` Position of the beam center on the detector .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` *ad hoc* canSAS_class. Obligatory value: ``container`` .. index:: x (data field) **x**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} .. index:: y (data field) **y**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} .. index:: z (data field) **z**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} While :math:`z` is allowed by the canSAS standard, it may not make sense to use it in some situations. Use of :math:`z` may be ignored by processing software. **pixel_size**: :ref:`NXparameters` size of the pixels on this detector. .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` *ad hoc* canSAS_class. Obligatory value: ``container`` .. index:: x (data field) **x**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} .. index:: y (data field) **y**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} .. index:: z (data field) **z**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} While :math:`z` is allowed by the canSAS standard, it may not make sense to use it in some situations. Use of :math:`z` may be ignored by processing software. **(source)**: :ref:`NXsource` Description of the radiation source. .. figure:: ../../../../contributed_definitions/SASsource.png :width: 60% The *SASsource* element .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` Official canSAS group: :index:`NXcanSAS (contributed definition); SASsource` Obligatory value: ``SASsource`` .. index:: radiation (data field) **radiation**: :ref:`NX_CHAR ` Name of the radiation used. Note that this is **not** the name of the facility! Any of these values: * ``Spallation Neutron Source`` * ``Pulsed Reactor Neutron Source`` * ``Reactor Neutron Source`` * ``Synchrotron X-ray Source`` * ``Pulsed Muon Source`` * ``Rotating Anode X-ray`` * ``Fixed Tube X-ray`` * ``UV Laser`` * ``Free-Electron Laser`` * ``Optical Laser`` * ``Ion Source`` * ``UV Plasma Source`` * ``neutron`` * ``x-ray`` * ``muon`` * ``electron`` * ``ultraviolet`` * ``visible light`` * ``positron`` * ``proton`` .. index:: beam_shape (data field) **beam_shape**: :ref:`NX_CHAR ` Text description of the shape of the beam (incident on the sample). .. index:: wavelength (data field) **wavelength**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_WAVELENGTH `} wavelength (:math:`\lambda`) of radiation incident on the sample .. index:: wavelength_min (data field) **wavelength_min**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_WAVELENGTH `} Some facilities specify wavelength using a range. This is the lowest wavelength in such a range. .. index:: wavelength_max (data field) **wavelength_max**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_WAVELENGTH `} Some facilities specify wavelength using a range. This is the highest wavelength in such a range. .. index:: wavelength_spread (data field) **wavelength_spread**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_WAVELENGTH `} Some facilities specify wavelength using a range. This is the width of such a range. **beam_size**: :ref:`NXparameters` Physical dimension of the beam (incident on the sample). If beam is round, just use :math:`x`. .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` *ad hoc* canSAS_class. Obligatory value: ``container`` .. index:: x (data field) **x**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} .. index:: y (data field) **y**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} .. index:: z (data field) **z**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_LENGTH `} While :math:`z` is allowed by the canSAS standard, it may not make sense to use it in some situations. Use of :math:`z` may be ignored by processing software. **(sample)**: :ref:`NXsample` Description of the sample. .. figure:: ../../../../contributed_definitions/SASsample.png :width: 60% The *SASsample* element .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` Official canSAS group: :index:`NXcanSAS (contributed definition); SASsample` Obligatory value: ``SASsample`` .. index:: ID (data field) **ID**: :ref:`NX_CHAR ` Text string that identifies this sample. .. index:: thickness (data field) **thickness**: :ref:`NX_FLOAT ` {units=\ :ref:`NX_LENGTH `} Thickness of this sample .. index:: transmission (data field) **transmission**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_DIMENSIONLESS `} Transmission (:math:`I/I_0`) of this sample. Note that there is no *units* attribute as this number is dimensionless. .. index:: temperature (data field) **temperature**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_TEMPERATURE `} Temperature of this sample. .. index:: details (data field) **details**: :ref:`NX_CHAR ` Any additional sample details. **position**: :ref:`NXtranslation` Location of the sample in :math:`x`, :math:`y`, and :math:`z`. **orientation**: :ref:`NXorientation` Orientation (rotation) of the sample. **(process)**: :ref:`NXprocess` Description of a processing or analysis step. .. figure:: ../../../../contributed_definitions/SASprocess.png :width: 60% The *SASprocess* element 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. .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` Official canSAS group: :index:`NXcanSAS (contributed definition); SASprocess` Obligatory value: ``SASprocess`` .. index:: name (data field) **name**: :ref:`NX_CHAR ` Optional name for this data processing or analysis step .. index:: date (data field) **date**: :ref:`NX_DATE_TIME ` Optional date for this data processing or analysis step. [#iso8601]_ .. [#iso8601] ISO-8601 standard time representation. Use a format for the date which is machine-readable such as 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. .. index:: description (data field) **description**: :ref:`NX_CHAR ` Optional description for this data processing or analysis step .. index:: term (data field) **term**: :ref:`NX_CHAR ` 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. The name *term* is not required, it could take any name. **(collection)**: :ref:`NXcollection` Describes anything about *SASprocess* that is not already described. Any content not defined in the canSAS standard can be placed at this point. .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` Official canSAS group: :index:`NXcanSAS (contributed definition); SASprocessnote` Obligatory value: ``SASprocessnote`` **(collection)**: :ref:`NXcollection` Free form description of anything not covered by other elements. .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` Official canSAS group: :index:`NXcanSAS (contributed definition); SASnote` Obligatory value: ``SASnote`` **(data)**: :ref:`NXdata` This describes certain data obtained from a variable-wavelength source such as pulsed-neutron source. .. figure:: ../../../../contributed_definitions/SAStransmission_spectrum.png :width: 60% The *SAStransmission_spectrum* element .. index:: canSAS_class (attribute) **@canSAS_class**: :ref:`NX_CHAR ` Official canSAS group: :index:`NXcanSAS (contributed definition); SAStransmission_spectrum` Obligatory value: ``SAStransmission_spectrum`` .. index:: name (attribute) **@name**: :ref:`NX_CHAR ` 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 ====== ============================================== .. index:: timestamp (attribute) **@timestamp**: :ref:`NX_DATE_TIME ` ISO-8601 time [#iso8601]_ .. index:: lambda (data field) **lambda**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_WAVELENGTH `} Wavelength of the radiation. .. index:: T (data field) **T**: :ref:`NX_NUMBER ` {units=\ :ref:`NX_DIMENSIONLESS `} Transmission value (:math:`I/I_0`) .. index:: signal (attribute) **@signal**: :ref:`NX_CHAR ` Obligatory value: * ``1``: the default data to plot in this group .. index:: axes (attribute) **@axes**: :ref:`NX_CHAR ` Obligatory value: * ``T``: the wavelengths field corresponding to this transmission .. index:: uncertainty (attribute) **@uncertainty**: :ref:`NX_CHAR ` Estimate of the uncertainty of each "math:`T`. **Source**: Automatically generated from https://github.com/nexusformat/definitions/blob/master/contributed_definitions/NXcanSAS.nxdl.xml