cansas1d documentation: Difference between revisions

From canSAS
(rearranged items, promoted overview to come first)
(point at tagged version)
 
(70 intermediate revisions by 4 users not shown)
Line 1: Line 1:
==Disclaimer==
This manual has been superseded (replaced) by a PDF:


This description is meant to inform the community how to layout
http://svn.smallangles.net/trac/canSAS/browser/1dwg/tags/v1.0/doc/cansas-1d-1_0-manual.pdf?format=raw
the information within the XML files.  However, should the
information in this document and the [[cansas1d.xsd | 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==
 
===overview===
 
After an XML header, the root element of the file is SASroot which
contains one or more SASentry elements, each of which describes
a single experiment (data set, time-slice, step in a series, new
sample, etc.).  Details of the SASentry element are also
shown in the next figure.  Refer to the '''block diagram at SASroot level'''
for an alternative depiction.  See [[cansas1d.xml]] for an example XML file.
[[Image:cansas1d-v1-1-SASroot.png|thumb|block diagram at SASroot level]]
 
===block diagrams===
There are block diagrams available to describe the standard:
*[[media:cansas1d-v1-1-SASroot.png | SASroot]]
** SASentry (data set, time-slice, step in a series, new sample, etc.)
***Title (for this particular SASentry)
***Run (run number or ID number of experiment)
***[[media:cansas1d-v1-2-SASdata.png | SASdata]] (this is where the reduced 1-D SAS data is stored)
***[[media:cansas1d-v1-3-SASsample.png | SASsample]]
***[[media:cansas1d-v1-4-SASinstrument.png | SASinstrument]]
****[[media:cansas1d-v1-5-SASsource.png | SASsource]]
****[[media:cansas1d-v1-6-SAScollimation.png | SAScollimation]]
****[[media:cansas1d-v1-7-SASdetector.png | SASdetector]]
***[[media:cansas1d-v1-8-SASprocess.png | SASprocess]] (for each processing or analysis step)
*** SASnote (anything at all)
* [[media:cansas1d-v1-9-full.png | full block diagram]]
 
 
===required XML file header===
<pre>
<?xml version="1.0"?>
<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>
 
===alternative XML file header (referencing a stylesheet)===
<pre>
<?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"
>
</pre>
 
===XML layout for multiple experiments===
 
Each experiment is described with a single '''SASentry''' element.
The brief example below shows how multiple experiments can be included
in a single XML file.  (For the sake of brevity, the data for each experiment
has been omitted from the example below.)
 
<pre>
<?xml version="1.0"?>
<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"
>
  <SASentry name="071121.dat#S22">
    <!-- contents of the first experiment in the file go here -->
  </SASentry>
  <SASentry name="name attribute is optional">
    <!-- any number of additional experiments can be included, as desired -->
  </SASentry>
</SASroot>
</pre>
 
 
==Definition of terms==
 
See [[cansas1d_definition_of_terms]] for the complete list of terms (XML elements and XML attributes) in the canSAS 1-D standard.
 
==Rules==
 
[[Image:Q-geometry.jpg|thumb|definition of Q geometry for small-angle scattering]]
 
[[Image:Translation-orientation-geometry.jpg|thumb|definition of translation and orientation geometry]]
 
# Q=(4 &pi; / &lambda;) sin(&theta;) <br> where &lambda; is the wavelength of the radiation and 2&theta; is the angle through which the detected radiation has been scattered.
# units to be given in standard SI abbreviations (eg, 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)
# where reciprocal units need to be quoted the format shall be "1/abbreviation"
# Unicode characters MUST NOT be used
# axes:
##z is along the flight path (positive value in the direction of the detector)
##x is orthogonal to z in the horizontal plane (positive values increase to the right when viewed towards the incoming radiation)
##y is orthogonal to z and x in the vertical plane (positive values increase upwards)
#orientation (angles):
##roll is about z
##pitch is about x
##yaw is about y
 
Note:  translation and orientation geometry used by canSAS are consistent with:
#http://en.wikipedia.org/wiki/Cartesian_coordinate_system
#http://en.wikipedia.org/wiki/Right-hand_rule
#http://webhost5.nts.jhu.edu/reza/book/kinematics/kinematics.htm
 
==Validation of XML against the Schema==
# open browser to:  http://www.xmlvalidation.com/
# paste content of candidate XML file (with reference in the header to the XML Schema as shown above) into the form
# press <validate>
# paste content of [[cansas1d.xsd]] XSD file into form and press <continue validation>
# check the results

Latest revision as of 04:39, 30 November 2009