cansas1d documentation: Difference between revisions

From canSAS
(Documentation for cansas1d is complete except for elimination of typos. Documentation is extracted from cansas1d.xsd.)
(standard header)
Line 12: Line 12:
<pre>
<pre>
<?xml version="1.0"?>
<?xml version="1.0"?>
<SASroot version="1.0">
<?xml-stylesheet type="text/xsl" href="example.xsl" ?>
<SASroot version="1.0"
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"
>
</pre>
</pre>


Revision as of 19:13, 25 January 2008

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"?>
<?xml-stylesheet type="text/xsl" href="example.xsl" ?>
<SASroot version="1.0"
	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"
	>

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 (element or attribute) is listed by its XPath in the XML file.
  • Elements are shown below sorted by their XPath. In the XML file, the order of elements is defined by the XML Schema. An example is given in the file: cansas1d_template.xml
  • Each term 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.
  • When shown in the template below with the "/@unit" XPath, the "unit" attribute is required.


/SASroot
[1..1] The canSAS reduced 1-D SAS data will be in the SASroot database. This is similar to NXroot used by NeXus.
/SASroot/@version
[1..1] version="1.0" Required attribute to indicate the version of the standard to which this XML document is encoded.
/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/SASentry/@name
[0..1] Optional string attribute to identify this particular 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. Note: 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/SASdata/@name
[0..1] Optional string attribute to identify this particular SASdata.
/SASroot/SASentry/SASdata/Idata
[1..inf] Idata describes a single SAS data point.
/SASroot/SASentry/SASdata/Idata/I
[1..1] Intensity of the detected radiation.
/SASroot/SASentry/SASdata/Idata/I/@unit
[1..1] Required unit for I. (See @unit for details.)
/SASroot/SASentry/SASdata/Idata/Idev
[1..1] Estimated standard deviation of I. Must specify the unit as an attribute.
/SASroot/SASentry/SASdata/Idata/Idev/@unit
[1..1] Required unit for Idev. (See @unit for details.)
/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.
/SASroot/SASentry/SASdata/Idata/Q/@unit
[1..1] Required unit for Q. (See @unit for details.)
/SASroot/SASentry/SASdata/Idata/Qdev
[0..1] Estimated standard deviation of Q. Must specify the unit as an attribute.
/SASroot/SASentry/SASdata/Idata/Qdev/@unit
[1..1] Required unit for Qdev. (See @unit for details.)
/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/Qfwhm/@unit
[1..1] Required unit for Qfwhm. (See @unit for details.)
/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/Qmean/@unit
[1..1] Required unit for Qmean. (See @unit for details.)
/SASroot/SASentry/SASdata/Idata/Shadowfactor
[0..1] Describes the adjustment due to the beam stop penumbra. (This definition needs revision. NIST?) NOTE: There is no "unit" attribute.
/SASroot/SASentry/SASinstrument
[1..1] Description of the instrument.
/SASroot/SASentry/SASinstrument/name
[1..1] Name of the instrument.
/SASroot/SASentry/SASinstrument/SAScollimation
[] Description of the instrument collimation.
/SASroot/SASentry/SASinstrument/SAScollimation/@name
[0..1] Optional text to describe this collimation element. (This is redundant with, but not the same as, /SASroot/SASentry/SASinstrument/SAScollimation/name and should be removed.)
/SASroot/SASentry/SASinstrument/SAScollimation/aperture
[0..inf] Slit or aperture.
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/@name
[0..1] Optional name for this aperture.
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/@type
[1..1] Optional text to describe the type aperture (pinhole, 4-blade slit, Soller slit, ...).
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/distance
[0..1] Is this necessary? What is the difference between /SASroot/SASentry/SASinstrument/SAScollimation/distance and /SASroot/SASentry/SASinstrument/SAScollimation/aperture/distance?
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/distance/@unit
[1..1] distance requires a unit to be specified. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/size
[0..1] Opening dimensions of this aperture.
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/size/@name
[1..1] Optional attribute to clarify the name of this beam size.
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/size/x
[0..1] Dimension of the aperture in X.
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/size/x/@unit
[1..1] Required unit for the dimension of x. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/size/y
[0..1] Dimension of the aperture in Y.
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/size/y/@unit
[1..1] Required unit for the dimension of y. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/size/z
[0..1] Dimension of the aperture in Z. While this is allowed by the standard, it does not make much sense for small-angle scattering.
/SASroot/SASentry/SASinstrument/SAScollimation/aperture/size/z/@unit
[1..1] Required unit for the dimension of z. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SAScollimation/distance
[0..1] Distance from this collimation element to the sample.
/SASroot/SASentry/SASinstrument/SAScollimation/distance/@unit
[1..1] distance requires a unit to be specified. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector
[1..inf] Description of a single or composite detector.
/SASroot/SASentry/SASinstrument/SASdetector/beam_center
[0..1] Center of the beam on the detector in X and Y.
/SASroot/SASentry/SASinstrument/SASdetector/beam_center/@name
Optional attribute to clarify the name of this detector beam center.
/SASroot/SASentry/SASinstrument/SASdetector/beam_center/x
[0..1] Center of the beam on the detector in X.
/SASroot/SASentry/SASinstrument/SASdetector/beam_center/x/@unit
[1..1] Required unit for the dimension of x. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector/beam_center/y
[0..1] Center of the beam on the detector in Y.
/SASroot/SASentry/SASinstrument/SASdetector/beam_center/y/@unit
[1..1] Required unit for the dimension of y. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector/beam_center/z
[0..1] Center of the beam on the detector in Z. While this is allowed by the standard, it does not make much sense for small-angle scattering.
/SASroot/SASentry/SASinstrument/SASdetector/beam_center/z/@unit
[1..1] Required unit for the dimension of z. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector/name
[1..1] Name of the detector.
/SASroot/SASentry/SASinstrument/SASdetector/offset
[0..1] Offset of the detector position in X, Y, and Z.
/SASroot/SASentry/SASinstrument/SASdetector/offset/@name
Optional attribute to clarify the name of this beam size.
/SASroot/SASentry/SASinstrument/SASdetector/offset/x
[0..1] Offset of the detector position in X.
/SASroot/SASentry/SASinstrument/SASdetector/offset/x/@unit
[1..1] Required unit for the dimension of x. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector/offset/y
[0..1] Offset of the detector position in Y.
/SASroot/SASentry/SASinstrument/SASdetector/offset/y/@unit
[1..1] Required unit for the dimension of y. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector/offset/z
[0..1] Offset of the detector position in Z. While this is allowed by the standard, it does not make much sense for small-angle scattering.
/SASroot/SASentry/SASinstrument/SASdetector/offset/z/@unit
[1..1] Required unit for the dimension of z. (See @unit for details.)
/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/orientation/@name
Optional attribute to name this orientation.
/SASroot/SASentry/SASinstrument/SASdetector/orientation/pitch
[0..1] Optional rotation of the detector about the X axis (pitch).
/SASroot/SASentry/SASinstrument/SASdetector/orientation/pitch/@unit
[1..1] Required unit for the dimension of pitch. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector/orientation/roll
[0..1] Optional rotation of the detector about the Z axis (roll).
/SASroot/SASentry/SASinstrument/SASdetector/orientation/roll/@unit
[1..1] Required unit for the dimension of roll. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector/orientation/yaw
[0..1] Optional rotation of the detector about the Y axis (yaw).
/SASroot/SASentry/SASinstrument/SASdetector/orientation/yaw/@unit
[1..1] Required unit for the dimension of yaw. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector/pixel_size
[0..1] Size of detector pixels in X and Y.
/SASroot/SASentry/SASinstrument/SASdetector/pixel_size/@name
Optional attribute to clarify the name of this detector pixel size.
/SASroot/SASentry/SASinstrument/SASdetector/pixel_size/x
[0..1] Size of detector pixels in X.
/SASroot/SASentry/SASinstrument/SASdetector/pixel_size/x/@unit
[1..1] Required unit for the dimension of x. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector/pixel_size/y
[0..1] Size of detector pixels in Y.
/SASroot/SASentry/SASinstrument/SASdetector/pixel_size/y/@unit
[1..1] Required unit for the dimension of y. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector/pixel_size/z
[0..1] Size of detector pixels in Z. While this is allowed by the standard, it does not make much sense for small-angle scattering.
/SASroot/SASentry/SASinstrument/SASdetector/pixel_size/z/@unit
[1..1] Required unit for the dimension of z. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASdetector/SDD
[0..1] Distance between sample and detector. Must specify the unit as an attribute.
/SASroot/SASentry/SASinstrument/SASdetector/SDD/@unit
[1..1] Required unit for SDD. (See @unit for details.)
/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/SASdetector/slit_length/@unit
[1..1] Required unit for the slit length. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASsource
[] Description of the source of the radiation.
/SASroot/SASentry/SASinstrument/SASsource/@name
[0..1] Optional text description of the source of the radiation (incident on the sample). This can be different from /SASroot/SASentry/SASinstrument/SASsource/radiation.
/SASroot/SASentry/SASinstrument/SASsource/beam_shape
[0..1] Text description of the shape of the beam (incident on the sample).
/SASroot/SASentry/SASinstrument/SASsource/beam_size
[0..1] Physical dimension of the beam (incident on the sample). Note: If beam is round, just use X dimension. Note: While Z dimension is allowed by the standard, it does not make sense for small-angle scattering.
/SASroot/SASentry/SASinstrument/SASsource/beam_size/@name
Optional attribute to clarify the name of this beam size.
/SASroot/SASentry/SASinstrument/SASsource/beam_size/x
[0..1] Dimension of the beam size in X.
/SASroot/SASentry/SASinstrument/SASsource/beam_size/x/@unit
[1..1] Required unit for the dimension of x. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASsource/beam_size/y
[0..1] Dimension of the beam size in Y.
/SASroot/SASentry/SASinstrument/SASsource/beam_size/y/@unit
[1..1] Required unit for the dimension of y. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASsource/beam_size/z
[0..1] Dimension of the beam size in Z. While this is allowed by the standard, it does not make much sense for small-angle scattering.
/SASroot/SASentry/SASinstrument/SASsource/beam_size/z/@unit
[1..1] Required unit for the dimension of z. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASsource/radiation
[1..1] Name of the radiation used (neutron, X-ray, synchrotron X-ray, Cu Ka X-ray tube, ..."
/SASroot/SASentry/SASinstrument/SASsource/wavelength
[0..1] wavelength of radiation incident on the sample.
/SASroot/SASentry/SASinstrument/SASsource/wavelength/@unit
[1..1] wavelength of radiation requires a unit to be specified. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASsource/wavelength_max
[0..1] Some facilities specify wavelength using a range. The maximum of such a range is given by wavelength_max.
/SASroot/SASentry/SASinstrument/SASsource/wavelength_max/@unit
[1..1] wavelength_max requires a unit to be specified. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASsource/wavelength_min
[0..1] Some facilities specify wavelength using a range. The minimum of such a range is given by wavelength_min.
/SASroot/SASentry/SASinstrument/SASsource/wavelength_min/@unit
[1..1] wavelength_min requires a unit to be specified. (See @unit for details.)
/SASroot/SASentry/SASinstrument/SASsource/wavelength_spread
[0..1] Some facilities specify the width of the wavelength spectrum. The minimum of such a range is given by wavelength_spread.
/SASroot/SASentry/SASinstrument/SASsource/wavelength_spread/@unit
[1..1] wavelength_spread requires a unit to be specified. (See @unit for details.)
/SASroot/SASentry/SASnote
[1..] Free form description of anything not covered by other elements.
/SASroot/SASentry/SASprocess
[0..inf] Description of a processing or analysis step.
/SASroot/SASentry/SASprocess/@name
[0..1] Optional attribute to provide a name for this SASprocess. It is redundant with /SASroot/SASentry/SASprocess/name but it is not the same. It should probably be removed.
/SASroot/SASentry/SASprocess/date
[0..1] Optional date for this data processing or analysis step. *** SHOULD WE SPECIFY THE FORMAT FOR THE DATE? ***
/SASroot/SASentry/SASprocess/description
[0..1] Optional description for this data processing or analysis step.
/SASroot/SASentry/SASprocess/name
[0..1] Optional name for this data processing or analysis step.
/SASroot/SASentry/SASprocess/SASprocessnote
[1..inf] This element is used to describe anything about SASprocess that is not already described.
/SASroot/SASentry/SASprocess/term
[0..1] This is used to specify the value of a single variable, parameter, or term related to the SASprocess step.
/SASroot/SASentry/SASprocess/term/@name
[1..1] Name of the term.
/SASroot/SASentry/SASprocess/term/@unit
[1..1] Unit (string) of the term. (See @unit for details.)
/SASroot/SASentry/SASsample
[] Description of the sample.
/SASroot/SASentry/SASsample/@name
[0..1] Optional attribute to name this sample. (Should be the same as SASsample/ID)
/SASroot/SASentry/SASsample/details
[0..inf] Text string to supply additional sample details.
/SASroot/SASentry/SASsample/ID
[1..1] Text string that identifies this sample.
/SASroot/SASentry/SASsample/orientation
[0..1] Orientation (rotation) of the sample.
/SASroot/SASentry/SASsample/orientation/@name
Optional attribute to name this orientation.
/SASroot/SASentry/SASsample/orientation/pitch
[0..1] Optional rotation of the sample about the X axis (pitch).
/SASroot/SASentry/SASsample/orientation/pitch/@unit
[1..1] Required unit for the dimension of pitch. (See @unit for details.)
/SASroot/SASentry/SASsample/orientation/roll
[0..1] Optional rotation of the sample about the Z axis (roll).
/SASroot/SASentry/SASsample/orientation/roll/@unit
[1..1] Required unit for the dimension of roll. (See @unit for details.)
/SASroot/SASentry/SASsample/orientation/yaw
[0..1] Optional rotation of the sample about the Y axis (yaw).
/SASroot/SASentry/SASsample/orientation/yaw/@unit
[1..1] Required unit for the dimension of yaw. (See @unit for details.)
/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/position/@name
Optional attribute to name this position.
/SASroot/SASentry/SASsample/position/x
[0..1] Location of the sample in X.
/SASroot/SASentry/SASsample/position/x/@unit
[1..1] Required unit for the dimension of x. (See @unit for details.)
/SASroot/SASentry/SASsample/position/y
[0..1] Location of the sample in Y.
/SASroot/SASentry/SASsample/position/y/@unit
[1..1] Required unit for the dimension of y. (See @unit for details.)
/SASroot/SASentry/SASsample/position/z
[0..1] Location of the sample in Z. While this is allowed by the standard, it does not make much sense for small-angle scattering.
/SASroot/SASentry/SASsample/position/z/@unit
[1..1] Required unit for the dimension of z. (See @unit for details.)
/SASroot/SASentry/SASsample/temperature
[0..1] Temperature of this sample. Must specify the unit as an attribute.
/SASroot/SASentry/SASsample/temperature/@unit
[1..1] Required unit for temperature. (See @unit for details.)
/SASroot/SASentry/SASsample/thickness
[0..1] Thickness of this sample. Must specify the unit as an attribute.
/SASroot/SASentry/SASsample/thickness/@unit
[1..1] Required unit for thickness. (See @unit for details.)
/SASroot/SASentry/SASsample/transmission
[0..1] Transmission (1-attenuation) of this sample. Express this as a fraction, not as a percentage. NOTE: there is not "unit" attribute.
/SASroot/SASentry/Title
[1..1] Title of this SASentry.
@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)
orientation/pitch
[0..1] Rotation about about the X axis. Unit must be specified.
orientation/roll
[0..1] Rotation about about the Z axis. Unit must be specified.
orientation/yaw
[0..1] Rotation about about the Y axis. Unit must be specified.
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.
x, y, z
Coordinates for (x, y, z) values representing a position or dimension. Unit must be specified for each.

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">
Retrieved from "https://wiki.cansas.org/index.php?title=cansas1d_documentation&oldid=199"