cansas1d documentation: Difference between revisions

From canSAS
(point to verbal definitions rather than block diagrams; each verbal definition is a table and includes a reference to the appropriate block diagram)
(point at tagged version)
 
(53 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 ==
 
[[Image:cansas1d-v1-1-SASroot.png|thumb|block diagram at SASroot level]]
 
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.
Examples, Case Studies, and  other background information are below.  More discussion can be found on the [[1D_Data_Formats_Working_Group|canSAS 1D Data Formats Working Group]] page and its [[Talk:1D_Data_Formats_Working_Group|discussion]] page.  Details about
each specific field (XPath string, XML elements and attributes) are described
on the [[cansas1d_definition_of_terms]] page.
 
=== Basic elements of the cansas1d/1.0 standard ===
 
{|  border="1"
|-
! {{Headcellstyle}} | element
! {{Headcellstyle}} | description
|-
||
[[cansas1d_XML_header | XML header]]
||descriptive info required at the start of every XML file
|-
||
:[[cansas1d_SASroot | SASroot]]
||
|-
||
::[[cansas1d_SASentry | 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
|-
||
:::[[cansas1d_any | {any}]]
||any non-cansas1d/1.0 element can be used at this point
|-
||
:::[[cansas1d_SASdata | SASdata]]
||this is where the reduced 1-D SAS data is stored
|-
||
::::[[cansas1d_Idata | Idata]]
||a single data point in the dataset
|-
||
:::[[cansas1d_any | {any}]]
||any non-cansas1d/1.0 element can be used at this point
|-
||
:::[[cansas1d_SASsample | SASsample]]
||
|-
||
::::ID
||description of this sample
|-
||
::::thickness
||thickness of this sample
|-
||
::::transmission
||transmission of this sample
|-
||
::::temperature
||temperature of this sample
|-
||
::::[[cansas1d_position | position]]
||position of this sample
|-
||
::::[[cansas1d_orientation | orientation]]
||rotation of this sample
|-
||
::::details
||any other details about this sample
|-
||
::::[[cansas1d_any | {any}]]
||any non-cansas1d/1.0 element can be used at this point
|-
||
:::[[cansas1d_SASinstrument | SASinstrument]]
||
|-
||
::::[[cansas1d_SASsource | SASsource]]
||
|-
||
::::[[cansas1d_SAScollimation | SAScollimation]]
||
|-
||
::::[[cansas1d_SASdetector | SASdetector]]
||
|-
||
:::[[cansas1d_SASprocess | SASprocess]]
||for each processing or analysis step
|-
||
:::[[cansas1d_SASnote | SASnote]]
||anything at all
|}
 
=== required XML file header ===
<pre>
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="example.xsl" ?>
<SASroot version="1.0"
    xmlns="cansas1d/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="cansas1d/1.0 http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"
    >
</pre>
 
== Rules ==
 
[[Image:Q-geometry.jpg|thumb|definition of Q geometry for small-angle scattering]]
 
[[Image:Translation-orientation-geometry-2.jpg|thumb|definition of translation and orientation geometry]]
 
# canSAS1d/1.0 XML data files will adhere to the standard if they can successfully [[cansas1d_documentation#Validation_of_XML_against_the_Schema | validate]] against the established XML Schema ([http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd])
# 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"
# 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
# Unicode characters MUST NOT be used
# Binary data is not supported
 
=== Compatibility of Geometry Definitions ===
 
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://www.nexusformat.org/Coordinate_Systems
#http://mcstas.risoe.dk/documentation/tutorial/node6.html
#http://webhost5.nts.jhu.edu/reza/book/kinematics/kinematics.htm
 
The translation and orientation geometry definitions used
here are different than those used by
'''SHADOW''' ([http://www.nanotech.wisc.edu/shadow/ http://www.nanotech.wisc.edu/shadow/])
where the ''y'' and ''z'' axes are swapped
and the direction of ''x'' is changed.
 
== 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"?>
<?xml-stylesheet type="text/xsl" href="example.xsl" ?>
<SASroot version="1.0"
    xmlns="cansas1d/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="cansas1d/1.0 http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"
    >
  <SASentry name="071121.dat#S22">
    <!-- contents of the first experiment in the file go here -->
  </SASentry>
  <SASentry name="example temperature series">
    <!-- example with two SAS data sets related to the same sample -->
    <Title>title of this series</Title>
    <Run name="run1">42-001</Run>
    <Run name="run2">42-002</Run>
    <SASdata name="run1">
      <!-- data from 42-001 run comes here -->
    </SASdata>
    <SASdata name="run2">
      <!-- data from 42-002 run comes here -->
    </SASdata>
    <!-- other elements come here for this entry -->
  </SASentry>
  <SASentry name="other sample">
    <!-- any number of additional experiments can be included, as desired -->
    <!-- SASentry elements in the same XML file do not have to be related -->
  </SASentry>
</SASroot>
</pre>
 
= Documentation and Definitions =
 
* '''Documentation''': [[cansas1d_documentation]]  (this page)
* '''Definitions''':  [[cansas1d_definition_of_terms]]
* '''Block diagrams''': [[cansas1d_documentation#block_diagrams]]
 
== XML Schema ==
 
* '''XML Schema''': defines the rules for the XML file format ([http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd TRAC], [http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd SVN])
* [[xsd-documentation.xsl | XSL stylesheet]] (used to extract information shown on the [[cansas1d_definition_of_terms | Schema documentation page]])
 
== XML Stylesheets ==
 
* '''example.xsl''': XSLT stylesheets can be used to extract metadata or to convert into another file format.  The default canSAS stylesheet [[http://svn.smallangles.net/svn/canSAS/1dwg/trunk/example.xsl | example.xsl]] should be copied into the each folder with canSAS XML data file(s).  It can be used to display the data in a supporting WWW browser (such as Firefox or Internet Explorer) or to import into Microsoft Excel (with the added XML support in Excel).  By default, MS Windows binds '''*.xml''' files to start Internet Explorer.  Double-clicking on a canSAS XML data file with the '''example.xsl''' stylesheet in the same directory will produce a WWW page with the SAS data and selected metadata.
 
== Foreign Elements ==
 
== Examples and Case Studies ==
 
* [[cansas1d.xml | basic example]]: Note that, for clarity, only one row of data is shown.  This is probably a very good example to use as a starting point for creating XML files with a text editor.
* [[bimodal-test1.xml]]: Simulated SAS data to test size distribution calculation routines.
* [[cansas1d_casestudy_collagen | dry chick collagen]]: illustrates the minimum information necessary to meet the requirements of the standard format
* [[cansas1d_casestudy_af1410 | AF1410 steel]]: SANS study using magnetic contrast variation (with multiple samples and multiple data sets for each sample), the files can be viewed from TRAC (no description yet):  [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/ http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/]
* [[cansas1d-template.xml]]: This is used to test all the rules in the XML Schema.  This is probably not a very good example to use as a starting point for creating XML files with a text editor since it tests many of the special-case rules.
 
== Support tools for Visualization & Analysis software ==
 
=== IgorPro ===
 
An import/export tool for [http://www.wavemetrics.com/ IgorPro] has been created
([http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/IgorPro/cansasXML.ipf cansasXML.ipf]).
You can check out the <nowiki>IgorPro</nowiki> working directory from the SVN server (see below).
 
As of 2008-03-14,
* test suite of XML files developed
* the support can import the XML files into IgorPro
* Development of a GUI (to support the [http://usaxs.xor.aps.anl.gov/staff/ilavsky/irena.html Irena] package) has begun
* Development to add export capabilities (from IgorPro) back to the cansas1d/1.0 format has begun
 
== Software repositories ==
 
* '''TRAC''':      [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk]
* '''Subversion''': [http://svn.smallangles.net/svn/canSAS/1dwg http://svn.smallangles.net/svn/canSAS/1dwg]  <br />(<nowiki>svn checkout http://svn.smallangles.net/svn/canSAS/1dwg/trunk/ cansas-1dwg</nowiki>)
 
 
= 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