cansas1d documentation

Disclaimer

This description is meant to inform the community how to layout the information within the XML files. However, should the information in this document and the canSAS 1D SAS XML Schema differ, the XML Schema will be deemed to have the most correct description of the standard.

General Layout of the XML Data

required XML file header

<?xml version="1.0"?>
<SASroot version="1.0">

alternative XML file header (referencing a stylesheet)

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="example.xsl" ?>
<SASroot version="1.0">

overall file: layout of SASroot

• SASroot
  • SASentry
  • SASentry
  • SASentry ... (for each data set, time-slice, step in a series, new sample, etc.)

each data set: layout of the SASentry

• SASentry
  • Title
  • Run
  • SASdata (this is where the reduced 1-D SAS data is stored)
  • SASsample
  • SASinstrument
  • SASprocess
  • SASprocess
  • SASprocess... (for each processing or analysis step)
  • SASnote
  • SASnote
  • SASnote... (anything at all)

Definition of terms

Note:

• Each term is listed by its XPath in the XML file.
• Each element in the standard is shown with a comment embedded.
• The comment indicates
  • the name of the element,
  • how many times the element can be used,
    • [0..1] : element is optional but can only appear once within enclosing element
    • [1..1] : element is required and can only appear once within enclosing element
    • [1..inf] : element is required but can appear as many times as needed within enclosing element
    • [0..inf] : element is optional and can appear as many times as needed within enclosing element
    • [] : element is optional, number of appearances within enclosing element is not specified
  • and a short description.
• All elements, when present, must appear in the order shown below.
• When shown in the template below, the "unit" attribute is required.

@unit

Data unit to be given in standard SI abbreviations (e.g., m, cm, mm, nm, K) with the following exceptions: um=micrometres C=celsius A=Angstroms percent=%. fraction a.u.=arbitrary units none=no units are relevant (such as dimensionless)

x, y, z

Coordinates for (x, y, z) values representing a position or dimension. Unit must be specified for each.

position/x

[0..1] Translation in the horizontal direction, orthogonal to Y and Z. Positive X direction increases as defined by Y and Z. Unit must be specified.

position/y

[0..1] Translation along the vertical gravitational direction. Positive direction increases upward. Unit must be specified.

position/z

[0..1] Translation along the beam direction. Positive direction increases from source towards detector. Unit must be specified.

roll, pitch, yaw

Coordinates for (roll, pitch, yaw) values representing an orientation or rotation. Unit must be specified for each.

orientation/roll

[0..1] Rotation about about the Z axis. Unit must be specified.

orientation/pitch

[0..1] Rotation about about the X axis. Unit must be specified.

orientation/yaw

[0..1] Rotation about about the Y axis. Unit must be specified.

/SASroot/SASentry/SASdata/Idata/Q

[1..1] Q = (4 pi / lambda) sin(theta) where lambda is the wavelength of the radiation and 2theta is the angle through which the detected radiation has been scattered. Must specify the unit as an attribute.

/SASroot/SASentry/SASdata/Idata/I

[1..1] Intensity of the detected radiation. Must specify the unit as an attribute.

/SASroot/SASentry/SASdata/Idata/Qdev

[0..1] Estimated standard deviation of Q. Must specify the unit as an attribute.

/SASroot/SASentry/SASdata/Idata/Idev

[1..1] Estimated standard deviation of I. Must specify the unit as an attribute.

/SASroot/SASentry/SASdata/Idata/Qfwhm

[0..1] Q resolution of this datum, defined as full-width in Q at half-maximum intensity. Must specify the unit as an attribute.

/SASroot/SASentry/SASdata/Idata/Qmean

[0..1] Mean value of Q for this datum. Must specify the unit as an attribute.

/SASroot/SASentry/SASdata/Idata/Shadowfactor

[0..1] Describes the adjustment due to the beam stop penumbra. (This definition needs revision. NIST?)

/SASroot/SASentry/SASdata/Idata

[1..inf] Idata describes a single SAS data point.

/SASroot/SASentry/SASdata/@name

[0..1] Optional string attribute to identify this particular SASdata.

/SASroot/SASentry/SASsample/ID

[1..1] Text string that identifies this sample.

/SASroot/SASentry/SASsample/thickness

[0..1] Thickness of this sample. Must specify the unit as an attribute.

/SASroot/SASentry/SASsample/transmission

[0..1] Transmission (1-attenuation) of this sample. Express this as a fraction, not as a percentage.

/SASroot/SASentry/SASsample/temperature

[0..1] Temperature of this sample. Must specify the unit as an attribute.

/SASroot/SASentry/SASsample/position

[0..1] Location in X, Y, and Z of the sample. Must specify the unit as an attribute to each position.

/SASroot/SASentry/SASsample/orientation

[0..1] Orientation (rotation) of the sample. Must specify the unit as an attribute to each angle.

/SASroot/SASentry/SASsample/details

[0..inf] Text string to supply additional sample details.

/SASroot/SASentry/SASsample/@name

[0..1] Optional attribute to name this sample. (Should be the same as SASsample/ID)

/SASroot/SASentry/SASinstrument/SASdetector/name

[1..1] Name of the detector.

/SASroot/SASentry/SASinstrument/SASdetector/SDD

[0..1] Distance between sample and detector. Must specify the unit as an attribute.

/SASroot/SASentry/SASinstrument/SASdetector/offset

[0..1] Offset of the detector position in X, Y, and Z. Must specify the unit as an attribute.

/SASroot/SASentry/SASinstrument/SASdetector/orientation

[0..1] Orientation (rotation) of the detector in roll, pitch, and yaw. Must specify the unit as an attribute.

/SASroot/SASentry/SASinstrument/SASdetector/beam_center

[0..1] Center of the beam on the detector in X and Y. (Z offset is allowed but does not make sense for small-angle scattering.) Must specify the unit as an attribute.

/SASroot/SASentry/SASinstrument/SASdetector/pixel_size

[0..1] Size of detector pixels in X and Y. (Z size is allowed but does not make sense for small-angle scattering.) Must specify the unit as an attribute.

/SASroot/SASentry/SASinstrument/SASdetector/slit_length

[0..1] Slit length of the instrument for this detector. Must specify the unit as an attribute.

/SASroot/SASentry/SASinstrument/name

[1..1] Name of the instrument.

/SASroot/SASentry/SASinstrument/SASsource

[] Description of the source of the radiation.

/SASroot/SASentry/SASinstrument/SAScollimation

[] Description of the instrument collimation.

/SASroot/SASentry/SASinstrument/SASdetector

[1..inf] Description of a single or composite detector.

/SASroot/SASentry/Title

[1..1] Title of this SASentry.

/SASroot/SASentry/Run

[1..inf] Run identification for this SASentry. For many facilities, this is an integer. Use multiple instances of Run as needed. How to correlate this with SASinstrument configurations has not yet been defined.

/SASroot/SASentry/SASdata

[1..inf] Reduced 1-D SAS data for this SASentry. Use multiple SASdata elements to represent multiple frames.

/SASroot/SASentry/SASsample

[] Description of the sample.

/SASroot/SASentry/SASinstrument

[1..1] Description of the instrument.

/SASroot/SASentry/SASprocess

[0..inf] Description of a processing or analysis step.

/SASroot/SASentry/SASnote

[1..] Free form description of anything not covered by other elements.

/SASroot/SASentry/@name

[0..1] Optional string attribute to identify this particular SASentry.

/SASroot/SASentry

[1..] A single SAS scan is reported in a SASentry. A SASentry can use the optional "name" attribute to provide a string for this SASentry. Use of this string is not defined by this standard.

/SASroot/@version

[1..1] Required attribute to indicate the version of the standard to which this XML document is encoded. version="1.0"

/SASroot

[1..1] The canSAS reduced 1-D SAS data will be in the SASroot database. This is similar to NXroot used by NeXus.

attributes

name

type

unit

version

rules

1. no whitespace padding of value fields
2. Q=(4 π / λ) sin(θ)
   where λ is the wavelength of the radiation and 2θ is the angle through which the detected radiation has been scattered.
3. units to be given in standard SI abbreviations (eg, m, cm, mm, nm, K) with the following exceptions:
   1. um=micrometres
   2. C=celsius
   3. A=Angstroms
   4. percent=%.
   5. fraction
   6. a.u.=arbitrary units
   7. none=no units are relevant (such as dimensionless)
4. where reciprocal units need to be quoted the format shall be "1/abbreviation"
5. Unicode characters MUST NOT be used
6. axes:
   1. z is along the flight path (positive value in the direction of the detector)
   2. x is orthogonal to z in the horizontal plane (positive values increase to the right when viewed towards the incoming radiation)
   3. y is orthogonal to z and x in the vertical plane (positive values increase upwards)
7. angles:
   1. roll is about z
   2. pitch is about x
   3. yaw is about y

Validation of XML against the Schema

1. open browser to: http://www.xmlvalidation.com/
2. paste content of candidate XML file into the form
3. replace standard canSAS1D XML header with canSAS1D XML Schema validation header (see below)
4. press <validate>
5. paste content of cansas1d.xsd XSD file into form and press <continue validation>
6. check the results

alternative XML header for validating against the XML Schema

<?xml version="1.0"?>
<SASroot xmlns="http://www.smallangles.net/cansas1d"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.smallangles.net/cansas1d/ http://www.smallangles.net/cansas1d/1.0/cansas1d.xsd"
	version="1.0">