Structure of the canSAS2012 data format

make some brief comments about this structure

Note:

• Name attributes are allowed to be chosen by the data file writer. However, a name must adhere to the naming standard for name attributes and must be unique within the containing group.

  In some file containers, such as HDF5, the names of items in each group must be unique. To write the canSAS standard in HDF5/NeXus, use the @name attribute of a group as the group’s HDF5 name. Write the type as the @NX_class attribute and replace the “SAS” letters with ‘NX” in the group type. More on this in the HDF5 implementation titled: Binary: HDF5. Here’s an example in HDF5:

  SASroot
    @NX_class = "NXroot"
    sasentry01
      @NX_class = "NXentry"
  

• @ prefix is a notation in this documentation that means the named item is an attribute. When used, do not actually use the @ symbol.

• Occurrence describes how many times a particular item is allowed to or must appear. We use a notation of [s..f]. The s term indicates the minimum number of times the item is required to appear (where 0 means optional and 1 means required). The f term indicates the maximum number of times the item is allowed to appear (where inf means unlimited).

  notation	meaning
  [0..1]	the item is optional but may appear only once, if at all
  [1..1]	the item is required and must appear only once
  [1..inf]	the item is required and may appear one or more times

• Within each group, the order in which each item appears is not important.

SASroot

The SASroot group is the beginning of the canSAS structure. It is used to hold the data from one or more experiments, contained in one or more SASentry groups.

In an HDF5 file, it is not necessary to create this group but rather, one should use the root of the HDF file as the SASroot group.

Name	Type	Occurrence	Description
@file	string	[1..1]	original data file name
@time	string	[1..1]	date and time (ISO 8601 format) that this file was written
SASentry	group	[1..inf]	Each SASentry group contains the data (SAS and analysis) pertaining to measurements of a single sample.

This is an example of the SASroot group (subgroup information not shown)

TODO:

This example could be improved. Such as the filename and the name of the time attribute.

SASroot
  @file = "/home/pi/data/cansas-demo.dat"
  @time = "2012-12-28 11:58:47 CST"
  SASentry
    @name = "sasentry01"

SASentry

A single SAS scan is reported in a SASentry. Include as many SASentry elements as desired. They may contain related or unrelated data. Other items may be added to a SASentry group but these may be ignored by analysis or visualization software.

Name	Type	Occurrence	Description
@name	string	[1..1]	Unique identifier of this entry group. See the name note above. Example: @name="sasentry01"
@version	string	[0..1]	Specific version of the canSAS standard used to write this data. This must be a text (not numerical) representation. Example: @version="2.0"
Title	string	[0..1]	Description of this entry. Example: Title = "Glassy Carbon C4 12keV"
SASdata	group	[1..inf]	The reduced \(I(Q)\) SAS data. Each SASdata group contains the reduced SAS data from measurements of a single sample. Use multiple SASdata elements to represent multiple \(I(Q)\) measurements.
SASsample	group	[0..1]	Information about this sample.
SASinstrument	group	[0..1]	Information about the instrument that measured this data.
SASprocess	group	[0..inf]	Description of a processing or analysis step.
SASnote	group	[0..inf]	Free form description to describe anything not already described.

This is an example of the SASentry group (subgroup information not shown)

SASentry
  @name = "sasentry01"
  @version = "2.0"
  Title = "Glassy Carbon C4 12keV"
  SASdata
    @name = "sasdata01"
  SASsample
    @name = "sample"
  SASinstrument
    @name = "sasinstrument01"
  SASprocess
    @name = "sasprocess01"
  SASnote
    @name = "sasnote01"

SASdata

Contains the reduced data \(I(Q)\) for analysis from a single SAS measurement. The table below shows the terms that are defined as part of the canSAS standard. Additional terms may be specified, as indicated in the section titled SASdata: Adding Additional Data.

Note

For all numerical quantities, a units attribute is required.

Name	Type	Occurrence	Description
@name	string	[1..1]	Unique identifier of this data group. See the name note above. Example: @name="sasdata01"
@Q_indices	int array	[1..1]	Describes which indices of I provide Q-related data.
@I_axes	string array	[1..1]	Tells the names of the datasets for I for each index position.
@Mask_indices	int array	[1..1]	Describes which indices of I provide Mask-related data.
Q	float	[1..1] [1]	\(|Q|\), as defined in Q vector magnitude: .
Qx	float	[1..1]	\(\vec Q \cdot \hat x\), as defined in Q vector: .
Qy	float	[1..1]	\(\vec Q \cdot \hat y\), as defined in Q vector: .
Qz	float	[1..1]	\(\vec Q \cdot \hat z\), as defined in Q vector: .
I	float	[1..1]	The reduced SAS intensity data, as defined in Definition of Intensity: .
Mask	int	[0..1]	Array (same shape as I) that indicates which values of the I array should be used for analysis. (1 = use, 0 = ignore)
probe_type	string	[0..1]	Name of the radiation used. For maximum compatibility with NeXus, use one of these strings as defined in the NeXus NXsource definition for type or probe: [2] 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 neutron x-ray muon electron
wavelength	float	[0..1]	Wavelength of the incident radiation. May be a scalar or an array.
transmission	float	[0..1]	Sample transmission. May be a scalar or an array.
SASnote	group	[0..inf]	Free form description to describe anything not already described.

[1]	Either Q must be present or Qx, Qy, and Qz must all be present.

[2]	NeXus NXsource: http://download.nexusformat.org/doc/html/classes/base_classes/NXsource.html

This is an example of the SASdata group (subgroup information not shown)

SASdata
  @name = "sasdata01"
  @Q_indices = [0,]
  @I_axes = ["Q",]
  Q: float[]
    @units = "1/A"
  I: float[]
    @units = "1/cm"
    @uncertainty = "Idev"
  Idev: float[]
    @units = "1/cm"
  probe_type = "x-ray"
  wavelength = 1.0401
    @units = "A"

@Q_indices

Array attribute that describes which indices (of the I data object) are used to reference Q. The items in this array use zero-based indexing.

@I_axes

String array that describes the names of the data objects that correspond to the indices of the I object.

@Mask_indices

Array attribute that describes which indices (of the I data object) are used to reference Mask. The items in this array use zero-based indexing.

Mask

TODO: show how to use the mask and how NOT to use the mask

The point of the mask is to indicate which intensity values should be considered for analysis (value = 1) and which should be ignored (value = 0). To preserve the statistics, masking is a procedural operation, not a mathematical operation.

Example with multi-dimensional \(I(Q)\)

Compare with these examples:

• 2-D images
• 2-D masked image

Consider an example case of \(I(T,t,P,Q(t))\) where the intensity is a function of temperature, time, pressure, and \(Q\), respectively. Also, in this hypothetical case, the intensity was recorded on a two-dimensional grid of 100,512 size, including intensity uncertainties, and some of the grid must be masked to remove it from consideration for analysis. Thus, the intensity is a 5-dimensional array:

@I_axes=["Temperature","Time","Pressure","Q","Q"]

This specifies two types of information. First, this specifies the index positions for the various related data. Second, this specifies the names of the related datasets. Temperature varies in the first index, Time in the second, `Pressure in the third, and 2-D \(Q\) in the last two indices. In this particular case, since \(Q\) is also a function of time, we specify:

@Q_indices = [1,3,4]

where 1 indicates the position of the time index (second position) and 3,4 indicate the positions of the 2-D grid indices. As a final permutation, the mask was not a function of time for some reason but only a function of \(Q\), so that:

@Mask_indices = [3,4]

Putting this all together, with accompanying datasets:

Caution

TODO: Check this example!

SASdata
  @name = "sasdata01"
  @Q_indices = [1,3,4]
  @I_axes = ["Temperature","Time","Pressure","Q","Q"]
  @Mask_indices = [3,4]
  Qx: float[nTime,100,512]
    @units = "1/A"
  Qy: float[nTime,100,512]
    @units = "1/A"
  Qz: float[nTime,100,512]
    @units = "1/A"
  I: float[nTemperature,nTime,nPressure,100,512]
    @units = "1/cm"
    @uncertainty = "Idev"
  Idev: float[nTemperature,nTime,nPressure,100,512]
    @units = "1/cm"
  Mask: int[100,512]
  Temperature: float[nTemperature]
    @units = "K"
  Time: float[nTime]
    @units = "s"
  Pressure: float[nPressure]
    @units = "MPa"

SASsample

Note that transmission has been moved to the SASdata group.

Name	Type	Occurrence	Description
@name	string	[1..1]	Unique identifier of this sample group. See the name note above. Example: @name="sample"
Title	string	[0..1]	Description of this sample. Example: Title = "Glassy Carbon C4 12keV"
thickness	float	[0..1]	Thickness of this sample.
temperature	float	[0..1]	Temperature of this sample.
position	group	[0..1]	Translation position of this sample.
orientation	group	[0..1]	Rotational orientation of this sample.
details	string	[0..1]	Any additional sample details: details = "obtained from the XYZ Company, batch #123456.7890"

SASinstrument

Since the canSAS standard is intended to describe reduced small-angle scattering data, the need for an elaborate SASinstrument group is minimal. Indeed, this group is here merely for compatibility with instrumental descriptions of the raw data and is not necessary for routine small-angle scattering data analysis.

SASnote

A SASnote group may contain any information. The contents of SASnote are left unspecified by the canSAS standard. It is used to specify additional information that has no specified place in the canSAS standard.

SASprocess

Parameters used in processing or determined as a result of processing may be stored either in SASnote groups or in individual datasets. The names must adhere to the naming standard for name attributes and must be unique within the containing group.

Name	Type	Occurrence	Description
@name	string	[1..1]	Unique identifier of this process group. See the name note above. Example: @name="sasprocess01"
Title	string	[0..1]	Description of this processing step. Example: Title = "Irena regularization analysis"
date	string	[0..1]	Optional date for this data processing or analysis step. The date is to be written in the ISO-8601 format. [3] Example: date = "2012-12-28 11:59:41 CST"
description	string	[0..1]	Optional description for this data processing or analysis step. Example: description = "first try at analysis"
SASnote	group	[0..inf]	Free form description to describe anything not already described.

[3]	ISO-8601 is a format for the date which is easily machine-readable (either yyyy-mm-ddThh:mm:ss or 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.