canSAS - User contributions [en]

cansas1d documentation

2008-05-12T22:05:12Z

122.104.184.195: /* Usage Notes */

= 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 [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd cansas1d/1.0 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-10-minimum.png|thumb|block diagram of minimum elements required for cansas1d/1.0 standard]]

The basic elements of the cansas1d/1.0 standard are shown in the following table.
After an XML header, the root element of the file is [[cansas1d_SASroot | SASroot]] which
contains one or more [[cansas1d_SASentry | SASentry]] elements, each of which describes
a single experiment (data set, time-slice, step in a series, new
sample, etc.). Details of the [[cansas1d_SASentry | SASentry]] element are also
shown in the next figure. Refer to the [[cansas1d_block_diagrams | block diagrams]]
for alternative depictions. See [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml 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.

* [[cansas1d_SASroot | '''SASroot''': the root element of the file (after the XML header)]]
* [[cansas1d_SASentry | '''SASentry''': describes a single experiment (data set, time-slice, step in a series, new sample, etc.)]]
* [[cansas1d_block_diagrams | block diagrams]]
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml cansas1d.xml] example XML file
* discussion of this format: [[1D_Data_Formats_Working_Group | basic]] [[Talk:1D_Data_Formats_Working_Group | more]]
* [[# Help_for_XML | Seek outside help for XML]]
* [[cansas1d_definition_of_terms | '''Definition of terms''': Details about each specific field (XPath string, XML elements and attributes)]]

=== Basic elements of the cansas1d/1.0 standard ===

{|
|-
! {{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_SASdata | 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]]
||
|| description of the sample
|-
||
:::[[cansas1d_SASinstrument | SASinstrument]]
||
|| description of the instrument
|-
||
::::[[cansas1d_SASsource | SASsource]]
||
|| description of the source
|-
||
::::[[cansas1d_SAScollimation | SAScollimation]]
||
|| description of the collimation
|-
||
::::[[cansas1d_SASdetector | SASdetector]]
||
|| description of the detector
|-
||
:::[[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/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd cansas1d.xsd])
# Q=(4 π / λ) sin(θ) where λ is the wavelength of the radiation and 2θ 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"
# when raised to a power, use similar to "A^3" or "1/m^4" (and not "A3" or "m-4")
# 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.

= Documentation and Definitions =

* '''Documentation''': [[cansas1d_documentation]] (this page)
* '''Definitions''': [[cansas1d_definition_of_terms]]
* '''Block diagrams''': [[cansas1d_block_diagrams]]

== XML Schema ==

'''XML Schema''': The [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd cansas1d.xsd] [http://www.w3schools.com/xsd 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]) and is used to validate
any XML file for adherence to the format.

== XML Stylesheets ==

* '''example.xsl''': [http://www.w3schools.com/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 [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/example.xsl '''example.xsl'''] stylesheet in the same directory will produce a WWW page with the SAS data and selected metadata.

== Examples and Case Studies ==

* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml 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.
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/bimodal-test1.xml 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/]
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d-template.xml 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.

=== XML layout for multiple experiments ===

Each experiment is described with a single '''SASentry''' element.
The fragment below shows how multiple experiments can be included
in a single XML file. Full examples of canSAS XML files with multiple experiments include:
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/W1W2.XML ISIS LOQ SANS instrument]
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cs_af1410.xml NIST SANS data]

<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">

</SASentry>
<SASentry name="example temperature series">

<Title>title of this series</Title>
<Run name="run1">42-001</Run>
<Run name="run2">42-002</Run>
<SASdata name="run1">

</SASdata>
<SASdata name="run2">

</SASdata>

</SASentry>
<SASentry name="other sample">


</SASentry>
</SASroot>
</pre>

== Foreign Elements ==

To allow for inclusion of elements that are not defined by the cansas1d.xsd XML Schema,
XML ''foreign elements'' are permitted at select locations in the cansas1d/1.0 format.
Please refer to the references (and others) [[#Help_for_XML | below]] for deeper discussions on foreign elements.

An example of the use of foreign elements in the cansas1d/1.0 format is given by
* http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/xg009036_001.xml

== Support tools for Visualization & Analysis software ==

(under development as of May 2008)

=== 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

====Usage Notes====
#To use the canSASxml.ipf procedure you must have the XMLutils.XOP IGOR plugin installed. This may be downloaded from the [http://www.igorexchange.com/project/XMLutils IgorExchange Project] site. There are installer executables contained in the download that will do all the installation for you. They will place the XOP in the folder ''/User Procedures/motofit/XMLutils'', and create a shortcut/alias to the plugin in /Igor Extensions.
Packages from other facilities should place the XOP there as well.

== 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] (<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 [http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd cansas1d.xsd] XSD file into form and press <continue validation>
# check the results

= Help for XML =
; XML: EXtensible Markup Language http://www.w3schools.com/xml/ http://www.w3.org/XML/ http://en.wikipedia.org/wiki/XML http://www.zvon.org/xxl/XPathTutorial/General/examples.html
; XSL (or XSLT): EXtensible Stylesheet Language http://www.w3schools.com/xsl/ http://www.w3.org/Style/XSL/ http://en.wikipedia.org/wiki/Extensible_Stylesheet_Language http://en.wikipedia.org/wiki/XSLT
; XPath: XPath is a language for finding information in an XML document. http://www.w3schools.com/xpath/ http://www.w3.org/Style/XSL/ http://en.wikipedia.org/wiki/XPath
; Schema: An XML Schema describes the structure of an XML document. http://www.w3schools.com/schema/ http://www.w3.org/XML/Schema http://en.wikipedia.org/wiki/XSD
; XML Namespaces: XML namespaces are used for providing uniquely named elements and attributes in an XML instance. http://www.zvon.org/xxl/NamespaceTutorial/Output http://en.wikipedia.org/wiki/XML_namespaces http://www.w3schools.com/XML/xml_namespaces.asp
; XML Foreign Elements: Inclusion of elements, at select locations, that are not defined by the cansas1d.xsd XML Schema http://books.xmlschemata.org/relaxng/relax-CHP-11-SECT-4.html http://www.w3.org/TR/SVG/extend.html http://www.google.com/search?q=XML+foreign+elements

cansas1d documentation

2008-05-12T22:04:45Z

122.104.184.195: /* Usage Notes */

= 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 [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd cansas1d/1.0 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-10-minimum.png|thumb|block diagram of minimum elements required for cansas1d/1.0 standard]]

The basic elements of the cansas1d/1.0 standard are shown in the following table.
After an XML header, the root element of the file is [[cansas1d_SASroot | SASroot]] which
contains one or more [[cansas1d_SASentry | SASentry]] elements, each of which describes
a single experiment (data set, time-slice, step in a series, new
sample, etc.). Details of the [[cansas1d_SASentry | SASentry]] element are also
shown in the next figure. Refer to the [[cansas1d_block_diagrams | block diagrams]]
for alternative depictions. See [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml 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.

* [[cansas1d_SASroot | '''SASroot''': the root element of the file (after the XML header)]]
* [[cansas1d_SASentry | '''SASentry''': describes a single experiment (data set, time-slice, step in a series, new sample, etc.)]]
* [[cansas1d_block_diagrams | block diagrams]]
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml cansas1d.xml] example XML file
* discussion of this format: [[1D_Data_Formats_Working_Group | basic]] [[Talk:1D_Data_Formats_Working_Group | more]]
* [[# Help_for_XML | Seek outside help for XML]]
* [[cansas1d_definition_of_terms | '''Definition of terms''': Details about each specific field (XPath string, XML elements and attributes)]]

=== Basic elements of the cansas1d/1.0 standard ===

{|
|-
! {{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_SASdata | 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]]
||
|| description of the sample
|-
||
:::[[cansas1d_SASinstrument | SASinstrument]]
||
|| description of the instrument
|-
||
::::[[cansas1d_SASsource | SASsource]]
||
|| description of the source
|-
||
::::[[cansas1d_SAScollimation | SAScollimation]]
||
|| description of the collimation
|-
||
::::[[cansas1d_SASdetector | SASdetector]]
||
|| description of the detector
|-
||
:::[[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/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd cansas1d.xsd])
# Q=(4 π / λ) sin(θ) where λ is the wavelength of the radiation and 2θ 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"
# when raised to a power, use similar to "A^3" or "1/m^4" (and not "A3" or "m-4")
# 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.

= Documentation and Definitions =

* '''Documentation''': [[cansas1d_documentation]] (this page)
* '''Definitions''': [[cansas1d_definition_of_terms]]
* '''Block diagrams''': [[cansas1d_block_diagrams]]

== XML Schema ==

'''XML Schema''': The [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd cansas1d.xsd] [http://www.w3schools.com/xsd 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]) and is used to validate
any XML file for adherence to the format.

== XML Stylesheets ==

* '''example.xsl''': [http://www.w3schools.com/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 [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/example.xsl '''example.xsl'''] stylesheet in the same directory will produce a WWW page with the SAS data and selected metadata.

== Examples and Case Studies ==

* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml 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.
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/bimodal-test1.xml 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/]
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d-template.xml 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.

=== XML layout for multiple experiments ===

Each experiment is described with a single '''SASentry''' element.
The fragment below shows how multiple experiments can be included
in a single XML file. Full examples of canSAS XML files with multiple experiments include:
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/W1W2.XML ISIS LOQ SANS instrument]
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cs_af1410.xml NIST SANS data]

<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">

</SASentry>
<SASentry name="example temperature series">

<Title>title of this series</Title>
<Run name="run1">42-001</Run>
<Run name="run2">42-002</Run>
<SASdata name="run1">

</SASdata>
<SASdata name="run2">

</SASdata>

</SASentry>
<SASentry name="other sample">


</SASentry>
</SASroot>
</pre>

== Foreign Elements ==

To allow for inclusion of elements that are not defined by the cansas1d.xsd XML Schema,
XML ''foreign elements'' are permitted at select locations in the cansas1d/1.0 format.
Please refer to the references (and others) [[#Help_for_XML | below]] for deeper discussions on foreign elements.

An example of the use of foreign elements in the cansas1d/1.0 format is given by
* http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/xg009036_001.xml

== Support tools for Visualization & Analysis software ==

(under development as of May 2008)

=== 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

====Usage Notes====
#To use the canSASxml.ipf procedure you must have the XMLutils.XOP IGOR plugin installed. This may be downloaded from the [http://www.igorexchange.com/project/XMLutils IgorExchange Project] site. There are installer executables contained in the download that will do all the installation for you. They will place the XOP in the folder ''/User Procedures/motofit/XMLutils'', and create a shortcut/alias to the plugin in /Igor Extension.
Packages from other facilities should place the XOP there as well.

== 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] (<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 [http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd cansas1d.xsd] XSD file into form and press <continue validation>
# check the results

= Help for XML =
; XML: EXtensible Markup Language http://www.w3schools.com/xml/ http://www.w3.org/XML/ http://en.wikipedia.org/wiki/XML http://www.zvon.org/xxl/XPathTutorial/General/examples.html
; XSL (or XSLT): EXtensible Stylesheet Language http://www.w3schools.com/xsl/ http://www.w3.org/Style/XSL/ http://en.wikipedia.org/wiki/Extensible_Stylesheet_Language http://en.wikipedia.org/wiki/XSLT
; XPath: XPath is a language for finding information in an XML document. http://www.w3schools.com/xpath/ http://www.w3.org/Style/XSL/ http://en.wikipedia.org/wiki/XPath
; Schema: An XML Schema describes the structure of an XML document. http://www.w3schools.com/schema/ http://www.w3.org/XML/Schema http://en.wikipedia.org/wiki/XSD
; XML Namespaces: XML namespaces are used for providing uniquely named elements and attributes in an XML instance. http://www.zvon.org/xxl/NamespaceTutorial/Output http://en.wikipedia.org/wiki/XML_namespaces http://www.w3schools.com/XML/xml_namespaces.asp
; XML Foreign Elements: Inclusion of elements, at select locations, that are not defined by the cansas1d.xsd XML Schema http://books.xmlschemata.org/relaxng/relax-CHP-11-SECT-4.html http://www.w3.org/TR/SVG/extend.html http://www.google.com/search?q=XML+foreign+elements

cansas1d documentation

2008-05-12T22:03:59Z

122.104.184.195: /* IgorPro */

= 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 [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd cansas1d/1.0 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-10-minimum.png|thumb|block diagram of minimum elements required for cansas1d/1.0 standard]]

The basic elements of the cansas1d/1.0 standard are shown in the following table.
After an XML header, the root element of the file is [[cansas1d_SASroot | SASroot]] which
contains one or more [[cansas1d_SASentry | SASentry]] elements, each of which describes
a single experiment (data set, time-slice, step in a series, new
sample, etc.). Details of the [[cansas1d_SASentry | SASentry]] element are also
shown in the next figure. Refer to the [[cansas1d_block_diagrams | block diagrams]]
for alternative depictions. See [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml 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.

* [[cansas1d_SASroot | '''SASroot''': the root element of the file (after the XML header)]]
* [[cansas1d_SASentry | '''SASentry''': describes a single experiment (data set, time-slice, step in a series, new sample, etc.)]]
* [[cansas1d_block_diagrams | block diagrams]]
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml cansas1d.xml] example XML file
* discussion of this format: [[1D_Data_Formats_Working_Group | basic]] [[Talk:1D_Data_Formats_Working_Group | more]]
* [[# Help_for_XML | Seek outside help for XML]]
* [[cansas1d_definition_of_terms | '''Definition of terms''': Details about each specific field (XPath string, XML elements and attributes)]]

=== Basic elements of the cansas1d/1.0 standard ===

{|
|-
! {{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_SASdata | 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]]
||
|| description of the sample
|-
||
:::[[cansas1d_SASinstrument | SASinstrument]]
||
|| description of the instrument
|-
||
::::[[cansas1d_SASsource | SASsource]]
||
|| description of the source
|-
||
::::[[cansas1d_SAScollimation | SAScollimation]]
||
|| description of the collimation
|-
||
::::[[cansas1d_SASdetector | SASdetector]]
||
|| description of the detector
|-
||
:::[[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/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd cansas1d.xsd])
# Q=(4 π / λ) sin(θ) where λ is the wavelength of the radiation and 2θ 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"
# when raised to a power, use similar to "A^3" or "1/m^4" (and not "A3" or "m-4")
# 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.

= Documentation and Definitions =

* '''Documentation''': [[cansas1d_documentation]] (this page)
* '''Definitions''': [[cansas1d_definition_of_terms]]
* '''Block diagrams''': [[cansas1d_block_diagrams]]

== XML Schema ==

'''XML Schema''': The [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd cansas1d.xsd] [http://www.w3schools.com/xsd 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]) and is used to validate
any XML file for adherence to the format.

== XML Stylesheets ==

* '''example.xsl''': [http://www.w3schools.com/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 [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/example.xsl '''example.xsl'''] stylesheet in the same directory will produce a WWW page with the SAS data and selected metadata.

== Examples and Case Studies ==

* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml 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.
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/bimodal-test1.xml 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/]
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d-template.xml 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.

=== XML layout for multiple experiments ===

Each experiment is described with a single '''SASentry''' element.
The fragment below shows how multiple experiments can be included
in a single XML file. Full examples of canSAS XML files with multiple experiments include:
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/W1W2.XML ISIS LOQ SANS instrument]
* [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cs_af1410.xml NIST SANS data]

<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">

</SASentry>
<SASentry name="example temperature series">

<Title>title of this series</Title>
<Run name="run1">42-001</Run>
<Run name="run2">42-002</Run>
<SASdata name="run1">

</SASdata>
<SASdata name="run2">

</SASdata>

</SASentry>
<SASentry name="other sample">


</SASentry>
</SASroot>
</pre>

== Foreign Elements ==

To allow for inclusion of elements that are not defined by the cansas1d.xsd XML Schema,
XML ''foreign elements'' are permitted at select locations in the cansas1d/1.0 format.
Please refer to the references (and others) [[#Help_for_XML | below]] for deeper discussions on foreign elements.

An example of the use of foreign elements in the cansas1d/1.0 format is given by
* http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/xg009036_001.xml

== Support tools for Visualization & Analysis software ==

(under development as of May 2008)

=== 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

====Usage Notes====
#To use the canSASxml.ipf procedure you must have the XMLutils.XOP IGOR plugin installed. This may be downloaded from the [http://www.igorexchange.com/project/XMLutils IgorExchange Project] site. There are installer executables contained in the download that will do all the installation for you. They will place the XOP in the folder '''/User Procedures/motofit/XMLutil''', and create a shortcut/alias to the plugin in /Igor Extension.
Packages from other facilities should place the XOP there as well.

== 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] (<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 [http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd cansas1d.xsd] XSD file into form and press <continue validation>
# check the results

= Help for XML =
; XML: EXtensible Markup Language http://www.w3schools.com/xml/ http://www.w3.org/XML/ http://en.wikipedia.org/wiki/XML http://www.zvon.org/xxl/XPathTutorial/General/examples.html
; XSL (or XSLT): EXtensible Stylesheet Language http://www.w3schools.com/xsl/ http://www.w3.org/Style/XSL/ http://en.wikipedia.org/wiki/Extensible_Stylesheet_Language http://en.wikipedia.org/wiki/XSLT
; XPath: XPath is a language for finding information in an XML document. http://www.w3schools.com/xpath/ http://www.w3.org/Style/XSL/ http://en.wikipedia.org/wiki/XPath
; Schema: An XML Schema describes the structure of an XML document. http://www.w3schools.com/schema/ http://www.w3.org/XML/Schema http://en.wikipedia.org/wiki/XSD
; XML Namespaces: XML namespaces are used for providing uniquely named elements and attributes in an XML instance. http://www.zvon.org/xxl/NamespaceTutorial/Output http://en.wikipedia.org/wiki/XML_namespaces http://www.w3schools.com/XML/xml_namespaces.asp
; XML Foreign Elements: Inclusion of elements, at select locations, that are not defined by the cansas1d.xsd XML Schema http://books.xmlschemata.org/relaxng/relax-CHP-11-SECT-4.html http://www.w3.org/TR/SVG/extend.html http://www.google.com/search?q=XML+foreign+elements