3.5.3. NXcanSAS¶

NOTE: this page contains a DRAFT version, use this Redirect link to view the most current documentation of NXcanSAS.

Status:

contributed definition, extends NXobject, version 1.0

Description:

Implementation of the 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:: NXcollection, NXcollimator, NXdata, NXdetector, NXinstrument, NXorientation, NXparameters, NXprocess, NXsample, NXsource, NXsubentry, NXtranslation

Structure:

(subentry): NXsubentry
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 [1] specification as this is compatible with various community standards.

[1] The UDunits specification also includes instructions for derived units.

@canSAS_class: NX_CHAR

Official canSAS group: SASentry

Obligatory value: SASentry

@version: 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
definition: NX_CHAR

Official NeXus NXDL schema to which this subentry conforms.

Obligatory value: NXcanSAS

title: NX_CHAR

Title of this SASentry.

run: NX_CHAR

Run identification for this SASentry. For many facilities, this is an integer. Use multiple instances of run as needed.

@name: NX_CHAR

Optional string attribute to identify this particular run. Could use this to associate (correlate) multiple SASdata elements with run elements.

(data): NXdata
A SASData group contains reduced a single small-angle scattering data set that can be represented as or .

The SASdata element

Q can be either a vector () or a vector magnitude ()

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).

@canSAS_class: NX_CHAR

Official canSAS group: NXcanSAS (contributed definition); SASdata

Obligatory value: SASdata

@I_axes: 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).
@Q_indices: NX_CHAR
Array that describes which indices (of the 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 data object: one for time and two for Q position. Thus, in this example, the Q data is time-dependent: .
@Mask_indices: NX_CHAR
Array that describes which indices (of the 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 data object for Q position.
Q: NX_NUMBER {units=NX_PER_LENGTH}

Array of data to accompany .

The geometry.

may be represented either as the three-dimensional scattering vector or by the magnitude of the scattering vector, .

When we write , we may refer to either or both of or , depending on the context.

@uncertainty: 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.

I: NX_NUMBER

Array of intensity () data.

The intensity may be represented in one of these forms:

absolute units: differential cross-section per unit volume per unit solid angle (typical units: 1/cm/sr)

absolute units: differential cross-section per unit atom per unit solid angle (typical units: cm^2)

arbitrary units: 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 .

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.

@uncertainty: NX_CHAR

Typically the estimated standard deviation. 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.

Qmean: NX_CHAR {units=NX_PER_LENGTH}

Mean value of 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.

ShadowFactor: NX_CHAR {units=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): NXparameters

Supplementary Uncertainty Data

@canSAS_class: NX_CHAR

ad hoc canSAS group: NXcanSAS (contributed definition); SASuncertainties

Obligatory value: SASuncertainties
(instrument): NXinstrument

This the SAS instrument.

The SASinstrument element

@canSAS_class: NX_CHAR

Official canSAS group: NXcanSAS (contributed definition); SASinstrument

Obligatory value: SASinstrument

(collimator): NXcollimator

Description of a collimating element in the instrument.

The SAScollimation element

@canSAS_class: NX_CHAR

Official canSAS group: NXcanSAS (contributed definition); SAScollimation

Obligatory value: SAScollimation

length: NX_NUMBER {units=NX_LENGTH}

Amount/length of collimation inserted (as on a SANS instrument)

aperture: NXparameters

Description of a slit or aperture.

@canSAS_class: NX_CHAR

ad hoc canSAS_class.

Obligatory value: container

@name: NX_CHAR

Optional name attribute for this aperture

@type: NX_CHAR

Optional text attribute to describe the type of aperture (pinhole, 4-blade slit, Soller slit, ...).

distance: NX_NUMBER {units=NX_LENGTH}

Distance from this collimation element to the sample.

size: NXparameters

Opening dimensions of this aperture.

@canSAS_class: NX_CHAR

ad hoc canSAS_class.

Obligatory value: container

x: NX_NUMBER {units=NX_LENGTH}

Dimension of the collimation in .

y: NX_NUMBER {units=NX_LENGTH}

Dimension of the collimation in .

z: NX_NUMBER {units=NX_LENGTH}

Dimension of the collimation in .

While is allowed by the canSAS standard, it may not make sense to use it in some situations. Use of may be ignored by processing software.

(detector): NXdetector

Description of a detector in the instrument.

The SASdetector element

@canSAS_class: NX_CHAR

Official canSAS group: NXcanSAS (contributed definition); SASdetector

Obligatory value: SASdetector

name: NX_CHAR

Identifies the name of this detector

SDD: NX_NUMBER {units=NX_LENGTH}

Distance between sample and detector.

slit_length: NX_NUMBER {units=NX_PER_LENGTH}

Slit length of the instrument for this detector, expressed in the same units as .

offset: NXparameters

Offset of the detector position.

@canSAS_class: NX_CHAR

ad hoc canSAS_class.

Obligatory value: container

x: NX_NUMBER {units=NX_LENGTH}

y: NX_NUMBER {units=NX_LENGTH}

z: NX_NUMBER {units=NX_LENGTH}

While is allowed by the canSAS standard, it may not make sense to use it in some situations. Use of may be ignored by processing software.

orientation: NXparameters

The orientation element describes simple rotations about a single axis (rather than a full set of rotations as in a crystallographic context).

@canSAS_class: NX_CHAR

ad hoc canSAS_class.

Obligatory value: container

roll: NX_NUMBER {units=NX_LENGTH}

Roll is rotation about the axis.

pitch: NX_NUMBER {units=NX_LENGTH}

Pitch is rotation about the axis.

yaw: NX_NUMBER {units=NX_LENGTH}

Yaw is rotation about the axis.

beam_center: NXparameters

Position of the beam center on the detector

@canSAS_class: NX_CHAR

ad hoc canSAS_class.

Obligatory value: container

x: NX_NUMBER {units=NX_LENGTH}

y: NX_NUMBER {units=NX_LENGTH}

z: NX_NUMBER {units=NX_LENGTH}

While is allowed by the canSAS standard, it may not make sense to use it in some situations. Use of may be ignored by processing software.

pixel_size: NXparameters

size of the pixels on this detector.

@canSAS_class: NX_CHAR

ad hoc canSAS_class.

Obligatory value: container

x: NX_NUMBER {units=NX_LENGTH}

y: NX_NUMBER {units=NX_LENGTH}

z: NX_NUMBER {units=NX_LENGTH}

While is allowed by the canSAS standard, it may not make sense to use it in some situations. Use of may be ignored by processing software.

(source): NXsource

Description of the radiation source.

The SASsource element

@canSAS_class: NX_CHAR

Official canSAS group: NXcanSAS (contributed definition); SASsource

Obligatory value: SASsource

radiation: 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

beam_shape: NX_CHAR

Text description of the shape of the beam (incident on the sample).

wavelength: NX_NUMBER {units=NX_WAVELENGTH}

wavelength () of radiation incident on the sample

wavelength_min: NX_NUMBER {units=NX_WAVELENGTH}

Some facilities specify wavelength using a range. This is the lowest wavelength in such a range.

wavelength_max: NX_NUMBER {units=NX_WAVELENGTH}

Some facilities specify wavelength using a range. This is the highest wavelength in such a range.

wavelength_spread: NX_NUMBER {units=NX_WAVELENGTH}

Some facilities specify wavelength using a range. This is the width of such a range.

beam_size: NXparameters

Physical dimension of the beam (incident on the sample). If beam is round, just use .

@canSAS_class: NX_CHAR

ad hoc canSAS_class.

Obligatory value: container

x: NX_NUMBER {units=NX_LENGTH}

y: NX_NUMBER {units=NX_LENGTH}

z: NX_NUMBER {units=NX_LENGTH}

While is allowed by the canSAS standard, it may not make sense to use it in some situations. Use of may be ignored by processing software.

(sample): NXsample

Description of the sample.

The SASsample element

@canSAS_class: NX_CHAR

Official canSAS group: NXcanSAS (contributed definition); SASsample

Obligatory value: SASsample

ID: NX_CHAR

Text string that identifies this sample.

thickness: NX_FLOAT {units=NX_LENGTH}

Thickness of this sample

transmission: NX_NUMBER {units=NX_DIMENSIONLESS}

Transmission () of this sample. Note that there is no units attribute as this number is dimensionless.

temperature: NX_NUMBER {units=NX_TEMPERATURE}

Temperature of this sample.

details: NX_CHAR

Any additional sample details.

position: NXtranslation

Location of the sample in , , and .

orientation: NXorientation

Orientation (rotation) of the sample.

(process): NXprocess

Description of a processing or analysis step.

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.

@canSAS_class: NX_CHAR

Official canSAS group: NXcanSAS (contributed definition); SASprocess

Obligatory value: SASprocess

name: NX_CHAR

Optional name for this data processing or analysis step

date: NX_DATE_TIME

Optional date for this data processing or analysis step. [2]

[2] (1, 2)
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.

description: NX_CHAR

Optional description for this data processing or analysis step

term: 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): NXcollection

Describes anything about SASprocess that is not already described.

Any content not defined in the canSAS standard can be placed at this point.

@canSAS_class: NX_CHAR

Official canSAS group: NXcanSAS (contributed definition); SASprocessnote

Obligatory value: SASprocessnote

(collection): NXcollection

Free form description of anything not covered by other elements.

@canSAS_class: NX_CHAR

Official canSAS group: NXcanSAS (contributed definition); SASnote

Obligatory value: SASnote

(data): NXdata

This describes certain data obtained from a variable-wavelength source such as pulsed-neutron source.

The SAStransmission_spectrum element

@canSAS_class: NX_CHAR

Official canSAS group: NXcanSAS (contributed definition); SAStransmission_spectrum

Obligatory value: SAStransmission_spectrum

@name: 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

@timestamp: NX_DATE_TIME

ISO-8601 time [2]

lambda: NX_NUMBER {units=NX_WAVELENGTH}

Wavelength of the radiation.

T: NX_NUMBER {units=NX_DIMENSIONLESS}

Transmission value ()

@signal: NX_CHAR

Obligatory value:

1: the default data to plot in this group

@axes: NX_CHAR

Obligatory value:

T: the wavelengths field corresponding to this transmission

@uncertainty: NX_CHAR

Estimate of the uncertainty of each “math:T.