#### Previous topic

Metadata of the canSAS2012 data format

# Structure of the canSAS2012 data format¶

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:

 1 2 3 4 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)

 1 2 3 4 5 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.

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)

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 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.

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

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 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.

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.

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)$$¶

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!

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 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]

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.