source: 1dwg/trunk/doc/src/overview.xml @ 236

Last change on this file since 236 was 236, checked in by prjemian, 9 years ago

refs #22, new example files ready, XSLT is ready, need to prepare documentation and then can tag the v1.1 release

  • Property svn:keywords set to Date Revision Author HeadURL Id
File size: 61.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="xml"?>
3<!--
4########### SVN repository information ###################
5# $Date$
6# $Author$
7# $Revision$
8# $HeadURL$
9# $Id$
10########### SVN repository information ###################
11-->
12<chapter xml:id="wiki-chapter" xmlns="http://docbook.org/ns/docbook" version="5.0"
13    xmlns:xlink="http://www.w3.org/1999/xlink">
14    <title>Overview</title>
15    <!-- from: http://www.smallangles.net/wgwiki/index.php/cansas1d_documentation -->
16    <section xml:id="cansas1d_documentation-Objective">
17        <title>Objective</title>
18        <para>One of the first aims
19            <indexterm><primary>canSAS</primary><secondary>objective</secondary></indexterm>
20            <indexterm><primary>canSAS</primary><secondary>aims</secondary></indexterm>
21            of the <emphasis role="bold">canSAS</emphasis>
22            <indexterm><primary>canSAS</primary></indexterm>
23            (Collective Action for Nomadic Small-Angle Scatterers)
24            forum of users, software developers, and facility staff was to discuss
25            better sharing of SAS data analysis software. The <link
26                xlink:href="http://www.smallangles.net/canSAS">canSAS</link><footnote><para>
27                <link xlink:href="http://www.smallangles.net/canSAS"
28                    ><literal>http://www.smallangles.net/canSAS</literal></link></para></footnote>
29            identified that a significant need within the SAS
30            community can be satisfied by a robust, self-describing, text-based, standard format to
31            communicate reduced one-dimensional small-angle scattering data,
32            <literal>I(Q)</literal>,<indexterm><primary>I(Q)</primary></indexterm> 
33            between users
34            of our facilities. Our goal has been to define such a format that leaves the data file
35            instantly human-readable, editable in the simplest of editors, and importable by simple
36            text import filters in programs that need not recognise advanced structure in the file
37            nor require advanced programming interfaces. The file should contain both the primary
38            data of <literal>I(Q)</literal><indexterm><primary>I(Q)</primary></indexterm> 
39            and also any other descriptive information (metadata)
40            <indexterm significance="preferred"><primary>metadata</primary></indexterm>
41            about the sample, measurement, instrument, processing, or analysis steps. </para>
42        <para>The cansas1d/1.1
43            <indexterm><primary>cansas1d/1.1 standard</primary></indexterm> 
44            <indexterm><primary>canSAS</primary><secondary>objective</secondary></indexterm>
45            standard meets the objectives for a 1D standard, incorporating
46            metadata
47            <indexterm><primary>metadata</primary></indexterm>
48            about the measurement, parameters and results of processing or analysis steps.
49            Even multiple measurements (related or unrelated) may be included within a single XML
50            file. </para>
51        <section xml:id="cansas1d_documentation_Objective-Status">
52            <title>Status</title>
53            <para>Version 1.0 was tagged from the subversion repository on 2009-05-12 as no changes
54                were committed since January 2009. Use this command to checkout the tagged release.
55                <example>
56                    <title>Checkout tagged release from subversion repository.</title>
57                    <programlisting>svn checkout http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0 cansas1dwg-1.0</programlisting>
58                </example>
59            </para>
60            <para>Version 1.1 was tagged from the subversion repository on 2012-09-01 including
61                changes indicated on the TRAC site.  Tickets closed: 17, 18, 20, 21, 22.
62               
63                See
64                <link xlink:href="http://svn.smallangles.net/trac/canSAS/report/6?sort=ticket&amp;asc=1"
65                    ><literal>http://svn.smallangles.net/trac/canSAS/report/6?sort=ticket&amp;asc=1</literal></link>
66
67                <example>
68                    <title>Checkout tagged release from subversion repository.</title>
69                    <programlisting>svn checkout http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.1 cansas1dwg-1.1</programlisting>
70                </example>
71            </para>
72        </section>
73    </section>
74    <section xml:id="cansas1d_documentation-XMLLayout">
75        <title>General Layout of the XML Data</title>
76        <para>The canSAS 1-D standard for reduced 1-D SAS data is implemented using XML files. A
77            single file can contain SAS data from a single experiment or multiple experiments. All
78            types of relevant data (<literal>I(Q)</literal><indexterm><primary>I(Q)</primary></indexterm>,
79            metadata)
80            <indexterm><primary>metadata</primary></indexterm>
81            are described for each experiment. More details are provided below.</para>
82        <section xml:id="cansas1d_documentation-XMLLayout-Overview">
83            <title>Overview</title>
84            <para>The basic elements of the cansas1d/1.1 standard are shown in the following table.
85                After an XML header, the root element of the file is
86                <link xlink:href="#cansas1d_documentation-element-SASroot"
87                    ><literal>SASroot</literal></link>
88                <indexterm><primary>element</primary><secondary>SASroot</secondary></indexterm>
89                which contains one or more
90                <link xlink:href="#cansas1d_documentation-element-SASentry"
91                    ><literal>SASentry</literal></link>
92                <indexterm><primary>element</primary><secondary>SASentry</secondary></indexterm>
93                elements, each of which
94                describes a single experiment (data set, time-slice, step in a series, new sample,
95                etc.). Details of the <literal>SASentry</literal> element are also shown in the
96                next figure.
97                See the section titled <link
98                    xlink:href="#xml-data-file"
99                    >Example XML Data Files</link>
100                for examples of cansas1d/1.1 XML data files.
101                Examples, Case Studies, and other background information
102                are below. More discussion can be found on the
103                <link
104                    xlink:href="http://www.smallangles.net/wgwiki/index.php/1D_Data_Formats_Working_Group"
105                    >canSAS 1D Data Formats Working Group</link><footnote>
106                    <para>
107                        <link xlink:href="http://www.smallangles.net/wgwiki/index.php/1D_Data_Formats_Working_Group"
108                            ><literal>http://www.smallangles.net/wgwiki/index.php/1D_Data_Formats_Working_Group</literal></link>
109                    </para>
110                </footnote>
111                page and its
112                <link
113                    xlink:href="http://www.smallangles.net/wgwiki/index.php/Talk:1D_Data_Formats_Working_Group"
114                    >discussion</link><footnote>
115                    <para>
116                        <link xlink:href="http://www.smallangles.net/wgwiki/index.php/Talk:1D_Data_Formats_Working_Group"
117                            ><literal>http://www.smallangles.net/wgwiki/index.php/Talk:1D_Data_Formats_Working_Group</literal></link>
118                    </para>
119                </footnote>
120                page.  A
121                <link
122                    xlink:href="#cansas1d_documentation-Documentation-Definitions"
123                    >glossary</link>
124                <indexterm><primary>glossary</primary></indexterm>
125                defining the details about each specific field (XPath string, XML elements and attributes) is provided.
126                </para>
127            <figure>
128                <title>block diagram of minimum elements required for cansas1d/1.1 standard</title>
129                <mediaobject>
130                    <imageobject>
131                        <imagedata fileref="../../graphics/10-minimum.png" scalefit="1" width="200pt"/>
132                    </imageobject>
133                </mediaobject>
134            </figure>
135            <itemizedlist>
136                <listitem><para> 
137                        <link xlink:href="#cansas1d_documentation-element-SASroot"
138                            ><literal>SASroot</literal></link>:
139                        the root element of the file (after the XML header)
140                    </para></listitem>
141                <listitem>
142                    <para> 
143                        <link xlink:href="#cansas1d_documentation-element-SASentry"
144                            ><literal>SASentry</literal></link>:
145                        describes a single experiment (data set, time-slice, step in a
146                        series, new sample, etc.)
147                    </para>
148                </listitem>
149            </itemizedlist>
150            <example>
151                <title>Required header for cansas1d/1.1 XML files</title>
152                <indexterm significance="preferred">
153                    <primary>XML header</primary>
154                </indexterm>
155                <programlisting>&lt;?xml version="1.0"?>
156&lt;SASroot version="1.1"
157   xmlns="cansas1d/1.1"
158   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
159   xsi:schemaLocation="cansas1d/1.1"
160   http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"></programlisting>
161            </example>
162            <para>
163                <table frame="all">
164                    <title>Basic elements of the canSAS 1-D standard</title>
165                    <tgroup cols="2">
166                        <colspec colname="c1" colnum="1" colwidth="2*"/>
167                        <colspec colname="c2" colnum="2" colwidth="6*"/>
168                        <thead>
169                            <row>
170                                <entry><?dblatex bgcolor="[gray]{0.8}"?>Element</entry>
171                                <entry><?dblatex bgcolor="[gray]{0.8}"?>Description</entry>
172                            </row>
173                        </thead>
174                        <tbody>
175                            <row>
176                                <entry>XML Header</entry>
177                                <entry>descriptive info required at the start of every XML
178                                    file</entry>
179                            </row>
180                            <row>
181                                <entry>
182                                    <link xlink:href="#cansas1d_documentation-element-SASroot"
183                                        ><literal>SASroot</literal></link>
184                                    <indexterm><primary>element</primary><secondary>SASroot</secondary></indexterm> 
185                                </entry>
186                                <entry>root element of XML file</entry>
187                            </row>
188                            <row>
189                                <entry>
190                                    <link xlink:href="#cansas1d_documentation-element-SASentry"
191                                        ><literal>&#160;SASentry</literal></link>
192                                    <indexterm><primary>element</primary><secondary>SASentry</secondary></indexterm> 
193                                </entry>
194                                <entry>data set, time-slice, step in a series, new sample,
195                                    etc.</entry>
196                            </row>
197                            <row>
198                                <entry>
199                                    <literal>&#160;&#160;Title</literal>
200                                <indexterm><primary>element</primary><secondary>Title</secondary></indexterm>
201                                </entry>
202                                <entry>for this particular <literal>SASentry</literal></entry>
203                            </row>
204                            <row>
205                                <entry>
206                                    <literal>&#160;&#160;Run</literal>
207                                    <indexterm><primary>element</primary><secondary>Run</secondary></indexterm>
208                                </entry>
209                                <entry>run number or ID number of experiment</entry>
210                            </row>
211                            <row>
212                                <entry>
213                                    <link xlink:href="#cansas1d_documentation-element-any"
214                                        ><literal>&#160;&#160;{any}</literal></link>
215                                    <indexterm><primary>element</primary><secondary>&lt;any&gt;</secondary></indexterm>
216                                </entry>
217                                <entry>any <literal>cansas1d/1.1</literal> element can be used at this
218                                    point</entry>
219                            </row>
220                            <row>
221                                <entry>
222                                    <link xlink:href="#cansas1d_documentation-element-SASdata"
223                                        ><literal>&#160;&#160;SASdata</literal></link>
224                                    <indexterm><primary>element</primary><secondary>SASdata</secondary></indexterm>
225                                </entry>
226                                <entry>this is where the reduced 1-D SAS data is stored</entry>
227                            </row>
228                            <row>
229                                <entry>
230                                    <literal>&#160;&#160;&#160;Idata</literal>
231                                    <indexterm><primary>element</primary><secondary>Idata</secondary></indexterm>
232                                </entry>
233                                <entry>a single data point in the dataset</entry>
234                            </row>
235                            <row>
236                                <entry>
237                                    <link xlink:href="#cansas1d_documentation-element-SASdata"
238                                        ><literal>&#160;&#160;SAStransmission_spectrum</literal></link>
239                                    <indexterm><primary>element</primary><secondary>SAStransmission_spectrum</secondary></indexterm>
240                                </entry>
241                                <entry>this is where any transmission spectra may be stored</entry>
242                            </row>
243                            <row>
244                                <entry>
245                                    <literal>&#160;&#160;&#160;Tdata</literal>
246                                    <indexterm><primary>element</primary><secondary>Tdata</secondary></indexterm>
247                                </entry>
248                                <entry>a single data point in the transmission spectrum</entry>
249                            </row>
250                            <row>
251                                <entry>
252                                    <link xlink:href="#cansas1d_documentation-element-any"
253                                        ><literal>&#160;&#160;{any}</literal></link>
254                                    <indexterm><primary>element</primary><secondary>&lt;any&gt;</secondary></indexterm>
255                                </entry>
256                                <entry>any cansas1d/1.1 element can be used at this
257                                    point</entry>
258                            </row>
259                            <row>
260                                <entry>
261                                    <link xlink:href="#cansas1d_documentation-element-SASsample"
262                                        ><literal>&#160;&#160;SASsample</literal></link>
263                                    <indexterm><primary>element</primary><secondary>SASsample</secondary></indexterm>
264                                </entry>
265                                <entry>description of the sample</entry>
266                            </row>
267                            <row>
268                                <entry>
269                                    <link xlink:href="#cansas1d_documentation-element-SASinstrument"
270                                        ><literal>&#160;&#160;SASinstrument</literal></link>
271                                    <indexterm><primary>element</primary><secondary>SASinstrument</secondary></indexterm>
272                                </entry>
273                                <entry>description of the instrument</entry>
274                            </row>
275                            <row>
276                                <entry>
277                                    <link xlink:href="#cansas1d_documentation-element-SASsource"
278                                        ><literal>&#160;&#160;&#160;SASsource</literal></link>
279                                    <indexterm><primary>element</primary><secondary>SASsource</secondary></indexterm>
280                                </entry>
281                                <entry>description of the source</entry>
282                            </row>
283                            <row>
284                                <entry>
285                                    <link xlink:href="#cansas1d_documentation-element-SAScollimation"
286                                        ><literal>&#160;&#160;&#160;SAScollimation</literal></link>
287                                    <indexterm><primary>element</primary><secondary>SAScollimation</secondary></indexterm>
288                                </entry>
289                                <entry>description of the collimation</entry>
290                            </row>
291                            <row>
292                                <entry>
293                                    <link xlink:href="#cansas1d_documentation-element-SASdetector"
294                                        ><literal>&#160;&#160;&#160;SASdetector</literal></link>
295                                    <indexterm><primary>element</primary><secondary>SASdetector</secondary></indexterm>
296                                </entry>
297                                <entry>description of the detector</entry>
298                            </row>
299                            <row>
300                                <entry>
301                                    <link xlink:href="#cansas1d_documentation-element-SASprocess"
302                                        ><literal>&#160;&#160;SASprocess</literal></link>
303                                    <indexterm><primary>element</primary><secondary>SASprocess</secondary></indexterm>
304                                </entry>
305                                <entry>for each processing or analysis step</entry>
306                            </row>
307                            <row>
308                                <entry>
309                                    <link xlink:href="#cansas1d_documentation-element-SASnote"
310                                        ><literal>&#160;&#160;SASnote</literal></link>
311                                    <indexterm><primary>element</primary><secondary>SASnote</secondary></indexterm>
312                                </entry>
313                                <entry>anything at all</entry>
314                            </row>
315                        </tbody>
316                    </tgroup>
317                </table>
318            </para>
319            </section>
320    </section>
321    <section xml:id="cansas1d_documentation-rules">
322        <title>Rules</title>
323        <orderedlist>
324            <listitem>
325                <para>cansas1d/1.1 XML data files will adhere to the standard if they can
326                    successfully
327                    <link xlink:href="#cansas1d_documentation-schema_validation">validate</link>
328                    <indexterm>
329                        <primary>validation</primary>
330                        <secondary>against XML Schema</secondary>
331                    </indexterm>
332                    against the established XML Schema
333                    (<link 
334                        xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd"
335                        ><literal>canSAS1d.xsd</literal></link>).</para>
336            </listitem>
337            <listitem>
338                <para>
339                    <inlineequation>
340                        <mathphrase>
341                            <alt>
342                                Q=(4 \pi / \lambda) \sin(\theta)
343                            </alt>
344                        </mathphrase>
345                    </inlineequation>
346                    <indexterm>
347                        <primary>Q</primary>
348                    </indexterm>
349                </para>
350                <para>
351                    <indexterm>
352                        <primary>geometry</primary>
353                        <secondary>Q</secondary>
354                    </indexterm>
355                    where
356                    <inlineequation><mathphrase><alt>\lambda</alt></mathphrase></inlineequation> 
357                    is the wavelength of the radiation</para>
358                <para>and 
359                    <inlineequation><mathphrase><alt>2\theta</alt></mathphrase></inlineequation>
360                    is the angle through which the detected radiation has been
361                    scattered.</para>
362                <figure>
363                    <title>definition of Q geometry for small-angle scattering</title>
364                    <mediaobject>
365                        <imageobject>
366                            <imagedata fileref="../../graphics/Q-geometry.jpg" scalefit="1"
367                                width="200pt"/></imageobject>
368                    </mediaobject>
369                </figure>
370            </listitem>
371            <listitem>
372                <para>
373                    units
374                    <indexterm significance="preferred">
375                        <primary>unit</primary>
376                    </indexterm>
377                    <indexterm>
378                        <primary>units</primary>
379                        <see>unit</see>
380                    </indexterm>
381                    to be given in standard SI abbreviations (eg, m, cm, mm, nm, K)
382                    with the following exceptions: </para>
383                <orderedlist numeration="loweralpha">
384                    <listitem>
385                        <para>um=micrometres</para>
386                    </listitem>
387                    <listitem>
388                        <para>C=celsius</para>
389                    </listitem>
390                    <listitem>
391                        <para>A=Angstroms</para>
392                    </listitem>
393                    <listitem>
394                        <para>percent=%.</para>
395                    </listitem>
396                    <listitem>
397                        <para>fraction</para>
398                    </listitem>
399                    <listitem>
400                        <para>a.u.=arbitrary units</para>
401                    </listitem>
402                    <listitem>
403                        <para>none=no units are relevant (such as dimensionless)</para>
404                    </listitem>
405                </orderedlist>
406            </listitem>
407            <listitem>
408                <para> where reciprocal units need to be quoted the format shall be
409                    "1/abbreviation"</para>
410            </listitem>
411            <listitem>
412                <para> when raised to a power, use similar to "A^3" or "1/m^4" (and not "A3" or
413                    "A**3" or "m-4")</para>
414            </listitem>
415            <listitem>
416                <para> 
417                    axes:
418                    <indexterm>
419                        <primary>geometry</primary>
420                        <secondary>translation</secondary>
421                    </indexterm>
422                </para>
423                <orderedlist numeration="loweralpha">
424                    <listitem>
425                        <para>z is along the flight path (positive value in the direction of the
426                            detector)</para>
427                    </listitem>
428                    <listitem>
429                        <para>x is orthogonal to z in the horizontal plane (positive values
430                            increase to the right when viewed towards the incoming
431                            radiation)</para>
432                    </listitem>
433                    <listitem>
434                        <para>y is orthogonal to z and x in the vertical plane (positive values
435                            increase upwards)</para>
436                    </listitem>
437                    <listitem>
438                        <figure>
439                            <title>definition of translation and orientation geometry as viewed
440                                from the detector towards the source</title>
441                            <para>
442                                <indexterm>
443                                    <primary>geometry</primary>
444                                    <secondary>rotation</secondary>
445                                </indexterm>
446                                <informaltable>
447                                    <!--<title/>-->
448                                    <tgroup cols="2">
449                                        <tbody>
450                                            <row>
451                                                <entry>
452                                                    <mediaobject>
453                                                        <imageobject>
454                                                            <imagedata
455                                                                fileref="../../graphics/translation-orientation-geometry.jpg"
456                                                                width="200pt" scalefit="1"/>
457                                                        </imageobject>
458                                                        <caption>
459                                                            <para>as viewed from source</para>
460                                                        </caption>
461                                                    </mediaobject>
462                                                </entry>
463                                                <entry>
464                                                    <mediaobject>
465                                                        <imageobject>
466                                                            <imagedata
467                                                                fileref="../../graphics/translation-orientation-geometry-2.jpg"
468                                                                width="200pt" scalefit="1"/>
469                                                        </imageobject>
470                                                        <caption>
471                                                            <para>as viewed from detector</para>
472                                                        </caption>
473                                                    </mediaobject>
474                                                </entry>
475                                            </row>
476                                        </tbody>
477                                    </tgroup>
478                                </informaltable>
479                            </para>
480                        </figure>
481                    </listitem>
482                </orderedlist>
483            </listitem>
484            <listitem>
485                <para>orientation (angles) describes one-axis rotations (rotations about
486                    multiple axes require more information):
487                    <indexterm>
488                        <primary>geometry</primary>
489                        <secondary>orientation (rotation)</secondary>
490                    </indexterm>
491                </para>
492                <orderedlist numeration="loweralpha">
493                    <listitem>
494                        <para>roll is about z</para>
495                    </listitem>
496                    <listitem>
497                        <para>pitch is about x</para>
498                    </listitem>
499                    <listitem>
500                        <para>yaw is about y</para>
501                    </listitem>
502                </orderedlist>
503            </listitem>
504            <listitem>
505                <para> 
506                    Unicode characters MUST NOT be used
507                    <note>
508                        <para>Can UNICODE characters be permitted in v1.1 standard?</para>
509                    </note>
510                </para>
511            </listitem>
512            <listitem>
513                <para> Binary data is not supported</para>
514            </listitem>
515        </orderedlist>
516        <para>
517        </para>
518    </section>
519    <section xml:id="cansas1d_documentation-geometry_compatibility">
520        <title>Compatibility of Geometry Definitions</title>
521        <para>
522            Note: translation and orientation geometry used by canSAS are consistent with:
523            <indexterm>
524                <primary>geometry</primary>
525                <secondary>compatibility with other standards</secondary>
526            </indexterm>
527        </para>
528        <itemizedlist>
529            <listitem>
530                <para>Cartesian: <link xlink:href="http://en.wikipedia.org/wiki/Cartesian_coordinate_system"
531                    ><literal>http://en.wikipedia.org/wiki/Cartesian_coordinate_system</literal></link></para>
532            </listitem>
533            <listitem>
534                <para>Right-hand rule: <link xlink:href="http://en.wikipedia.org/wiki/Right-hand_rule"
535                    ><literal>http://en.wikipedia.org/wiki/Right-hand_rule</literal></link></para>
536            </listitem>
537            <listitem>
538                <para>NeXus:
539                    <indexterm><primary>NeXus</primary></indexterm>
540                    <link xlink:href="http://www.nexusformat.org/Coordinate_Systems"
541                    ><literal>http://www.nexusformat.org/Coordinate_Systems</literal></link></para>
542            </listitem>
543            <listitem>
544                <para><literal>McStas</literal>:
545                    <link xlink:href="http://mcstas.risoe.dk/documentation/tutorial/node6.html"
546                        ><literal>http://mcstas.risoe.dk/documentation/tutorial/node6.html</literal
547                        ></link></para>
548            </listitem>
549                <!-- PRJ, 2009-10-08: no longer available, this was a robotics book
550                    Now, that work is (from http://www.springer.com/engineering/book/978-0-387-32475-3)
551                    Theory of Applied Robotics
552                    Kinematics, Dynamics, and Control
553                    Jazar, Reza N.
554                    2007, XXI, 695 p. 200 illus., Hardcover
555                    ISBN: 978-0-387-32475-3
556                    <listitem>
557                    <para><link xlink:href="http://webhost5.nts.jhu.edu/reza/book/kinematics/kinematics.htm"
558                        ><literal>http://webhost5.nts.jhu.edu/reza/book/kinematics/kinematics.htm</literal></link></para>
559                </listitem>-->
560        </itemizedlist>
561        <para>The translation and orientation geometry definitions used here are different than
562            those used by <link xlink:href="http://www.nanotech.wisc.edu/shadow"
563                ><literal>SHADOW</literal></link><footnote><para>
564                <link xlink:href="http://www.nanotech.wisc.edu/shadow"
565                    ><literal>http://www.nanotech.wisc.edu/shadow</literal></link></para></footnote>
566            where the <emphasis role="italic">y</emphasis> and <emphasis role="italic"
567                >z</emphasis> axes are swapped and the direction of <emphasis role="italic"
568                    >x</emphasis> is changed.</para>
569    </section>
570    <section xml:id="cansas1d_documentation-converting_into_XML">
571        <title>Converting data into the XML format</title>
572        <para>The
573            <link xlink:href="http://www.smallangles.net/canSAS/xmlWriter/"
574                ><emphasis role="italic">canSAS/xmlWriter</emphasis></link><footnote>
575                <para><link xlink:href="http://www.smallangles.net/canSAS/xmlWriter/"
576                    ><literal>http://www.smallangles.net/canSAS/xmlWriter/</literal></link></para>
577            </footnote>
578            <indexterm><primary><literal>xmlWriter</literal></primary></indexterm>
579            is a WWW form
580            to translate three-column ASCII text data into the cansas1d/1.1 XML
581            format. This form will help you in creating an XML file with all the required
582            elements in the correct places. The form requests the SAS data of Q, I, and Idev
583            (defined elsewhere on this page) and some basic metadata
584            <indexterm><primary>metadata</primary></indexterm>
585            (title, run, sample info, ...). </para>
586        <para>Press the <code>Submit</code> button and you will receive a nicely
587            formatted WWW page with the SAS data. If you then choose <emphasis>View page source</emphasis>
588            (from one of your browser menus), you will see the raw XML of the cansas1d/1.1 XML format
589            and you can copy/paste this into an XML file. </para>
590        <para>The SAS data that you paste into the form box is likely to be copied directly from
591            a 3-column ASCII file from a text editor. Line breaks are OK, they will be treated
592            as white-space as will tabs and commas. Do not be concerned that the data looks
593            awful in the form entry box, just check the result to see that it comes out
594            OK.</para>
595    </section>
596    <section xml:id="cansas1d_documentation-Documentation-Definitions">
597        <title>Documentation and Definitions</title>
598        <section xml:id="cansas1d_documentation-XML_Schema">
599            <title>XML Schema</title>
600            <para> The
601                <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd"
602                    ><literal>cansas1d.xsd</literal></link>
603                <link xlink:href="http://www.w3schools.com/xsd"
604                    >XML Schema</link><footnote><para>
605                    <link xlink:href="http://www.w3schools.com/xsd"
606                        ><literal>http://www.w3schools.com/xsd</literal></link></para></footnote>
607                <indexterm><primary>XML Schema</primary></indexterm>
608                defines the rules for the XML file format<footnote>
609                    <para>
610                        TRAC:
611                        <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd"
612                            ><literal>http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd</literal></link>
613                    </para>
614                </footnote><footnote>
615                    <para>
616                        SVN:
617                        <link xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"
618                            ><literal>http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd</literal></link>
619                    </para>
620                </footnote>
621                and is used to
622                validate any XML file for adherence to the format. </para>
623        </section>
624        <section xml:id="cansas1d_documentation-XML_Stylesheets">
625            <title>XML Stylesheets</title>
626            <para>
627                XML stylesheets (also known as XSLT)<footnote>
628                    <para>
629                        <link xlink:href="http://www.w3schools.com/xsl/"
630                            ><literal>http://www.w3schools.com/xsl/</literal></link></para>
631                </footnote>
632                <indexterm>
633                    <primary>XML Stylesheet</primary>
634                </indexterm>
635                can be used to extract metadata
636                <indexterm><primary>metadata</primary></indexterm>
637                or to convert into another file format. The
638                default canSAS stylesheet <literal>cansasxml-html.xsl</literal><footnote>
639                    <para>
640                        <link xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansasxml-html.xsl"
641                            ><literal>http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansasxml-html.xsl</literal></link></para>
642                </footnote>
643                should be copied into each folder with canSAS XML data
644                file(s). It can be used to display the data in a supporting WWW browser
645                (such as Firefox or Internet Explorer) or to import into Microsoft Excel
646                (with the added XML support in Excel). (See the excellent write-up by Steve
647                King, ISIS,<footnote>
648                    <para>
649                        <link xlink:href="http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/xml/cansas_xml_format.pdf"
650                            ><literal>http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/xml/cansas_xml_format.pdf</literal></link>
651                    </para>
652                </footnote>
653                for an example.) By default, MS Windows binds <literal>*.xml</literal> files to start
654                Internet Explorer. Double-clicking on a canSAS XML data file with the
655                <literal>cansasxml-html.xsl</literal> (see above)
656                stylesheet in the same directory will produce a
657                WWW page with the SAS data and selected metadata.
658                <indexterm><primary>metadata</primary></indexterm>
659            </para>
660        </section>
661        <section xml:id="cansas1d_documentation-programming_suggestions">
662            <title>Suggestions for support software that write cansas1d/1.1 XML data files</title>
663            <para>
664                Some common best practices have been identified in the list below.
665                <indexterm><primary>file</primary><secondary>Writing cansas1d/1.1 files</secondary></indexterm>
666                <indexterm><primary>best practices</primary></indexterm>
667            </para>
668            <itemizedlist>
669                <listitem>
670                    <para>be sure to update to the latest SVN repository revision (command:
671                        <code>svn update</code>) </para>
672                </listitem>
673                <listitem>
674                    <para>check the output directory to see if it contains the default XSLT
675                        file.</para>
676                </listitem>
677                <listitem>
678                    <para>copy the latest XSLT file to the output directory if
679                        either:</para>
680                    <itemizedlist>
681                        <listitem>
682                            <para>the output directory contains an older revision</para>
683                        </listitem>
684                        <listitem>
685                            <para>the output directory does not have the default XSLT
686                                file</para>
687                        </listitem>
688                    </itemizedlist>
689                </listitem>
690                <listitem>
691                    <para>The most recent XSLT file can be identified by examining the file
692                        for the <literal>$ Revision: </literal> string such as in the next example.
693                        <informalexample>
694                            <programlisting># &#36;Revision: 111 $</programlisting>
695                        </informalexample>
696                    </para>
697                </listitem>
698            </itemizedlist>
699        </section>
700        <section xml:id="cansas1d_documentation-examples">
701            <title>Examples and Case Studies</title>
702            <itemizedlist>
703                <listitem>
704                    <para>
705                        Basic example:<footnote><para>
706                            <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml"
707                                ><literal
708                                    >http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml</literal
709                                ></link></para></footnote>
710                        <indexterm>
711                            <primary>XML file</primary>
712                            <secondary>cansas1d.xml</secondary>
713                        </indexterm>
714                        Note that, for clarity, only one row of data is
715                        shown. This is probably a very good example to use as a starting point for
716                        creating XML files with a text editor.</para>
717                </listitem>
718                <listitem>
719                    <para>
720                        Bimodal test data:<footnote><para>
721                            <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/bimodal-test1.xml"
722                                ><literal
723                                    >http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/bimodal-test1.xml</literal
724                                ></link></para></footnote>
725                        <indexterm>
726                            <primary>XML file</primary>
727                            <secondary>bimodal-test1.xml</secondary>
728                        </indexterm>
729                        <indexterm>
730                            <primary>case study</primary>
731                            <secondary>bimodal test data</secondary>
732                        </indexterm>
733                        Simulated SAS data (with added noise) calculated from model bimodal size
734                        distribution to test size distribution analysis routines.</para>
735                </listitem>
736                <listitem>
737                    <para>
738                        Glassy Carbon Round Robin:<footnote>
739                            <para>
740                            <link xlink:href="http://www.smallangles.net/wgwiki/index.php/Glassy_Carbon_Round_Robin"
741                                ><literal>http://www.smallangles.net/wgwiki/index.php/Glassy_Carbon_Round_Robin</literal
742                                ></link></para>
743                        </footnote>
744                        <indexterm>
745                            <primary>case study</primary>
746                            <secondary>glassy carbon round robin</secondary>
747                        </indexterm>
748                        Samples of a commercial glassy carbon
749                        measured at several facilities worldwide.</para>
750                </listitem>
751                <listitem>
752                    <para>SAXS data from
753                        <link xlink:href="#cansas1d_documentation-case_study-collagen"
754                            >dry chick collagen</link>
755                        <indexterm>
756                            <primary>case study</primary>
757                            <secondary>SAXS of dry chick collagen</secondary>
758                        </indexterm>
759                        illustrates the
760                        minimum information necessary to meet the requirements of the standard
761                        format</para>
762                </listitem>
763                <listitem>
764                    <para>SANS data from
765                        <link xlink:href="#cansas1d_documentation-case_study-af1410"
766                            >AF1410 steel</link>:<footnote><para>
767                                <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/"
768                                    ><literal>http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/</literal
769                                    ></link></para></footnote>
770                        <indexterm>
771                            <primary>case study</primary>
772                            <secondary>SANS of AF1410 steel</secondary>
773                        </indexterm>
774                        SANS study using magnetic
775                        contrast variation (with multiple samples and multiple data sets for each
776                        sample), the files can be viewed from the TRAC site (no description yet).</para>
777                </listitem>
778                <listitem>
779                    <para>
780                        <literal>cansas1d-template.xml</literal>:<footnote><para>
781                            <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d-template.xml"
782                                ><literal
783                                    >http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d-template.xml</literal
784                                ></link></para></footnote>
785                        <indexterm>
786                            <primary>XML file</primary>
787                            <secondary>cansas1d-template.xml</secondary>
788                        </indexterm>
789                        This is used to test all the rules in the XML
790                        Schema. This is probably not a very good example to use as a starting point
791                        for creating XML files with a text editor since it tests many of the
792                        special-case rules.</para>
793                </listitem>
794            </itemizedlist>
795            <section xml:id="cansas1d_documentation-examples-multiple_experiments">
796                <title>XML layout for multiple experiments</title>
797                <para>Each experiment is described with a single <literal>SASentry</literal> element. The
798                    fragment below shows how multiple experiments
799                    <indexterm>
800                        <primary>multiple experiments</primary>
801                    </indexterm>
802                    <indexterm>
803                        <primary>multiple data sets</primary>
804                    </indexterm>
805                    can be included in a single XML
806                    file. Full examples of canSAS XML files with multiple experiments
807                    include:</para>
808                <itemizedlist>
809                    <listitem>
810                        <para> ISIS LOQ SANS instrument:<footnote><para>
811                            <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/W1W2.XML"
812                                ><literal
813                                    >http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/W1W2.XML</literal
814                                ></link></para></footnote>
815                            <indexterm>
816                                <primary>XML file</primary>
817                                <secondary>W1W2.XML</secondary>
818                            </indexterm>
819                            multiple data sets.
820                        </para>
821                    </listitem>
822                    <listitem>
823                        <para> AF1410 steel SANS contrast variation study from NIST:<footnote><para>
824                                <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/cs_af1410.xml"
825                                    ><literal
826                                        >http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/cs_af1410.xml</literal
827                                    ></link></para></footnote>
828                            <indexterm>
829                                <primary>XML file</primary>
830                                <secondary>cs_af1410.xml</secondary>
831                            </indexterm>
832                            SANS study using magnetic
833                            contrast variation (with multiple samples and multiple data sets for each
834                            sample), the files can be viewed from the TRAC site (no description yet).
835                        </para>
836                    </listitem>
837                </itemizedlist>
838                <para>Here is a brief sketch of how a file would be arranged with multiple SASentry
839                    elements and multiple SASdata elements.
840                    <indexterm>
841                        <primary>XML file</primary>
842                        <secondary>brief-sketch-multiple.xml</secondary>
843                    </indexterm>
844                    <example>
845                        <title>Brief sketch of a file with multiple SASentry and SASdata blocks.</title>
846                        <programlisting language="xml" linenumbering="numbered">
847                            <textobject>
848                                <textdata fileref="brief-sketch-multiple.xml"/>
849                            </textobject>
850                        </programlisting>
851                    </example>
852                </para>
853            </section>
854        </section>
855        <section xml:id="cansas1d_documentation-Foreign_Elements">
856            <title>Foreign Elements</title>
857            <para> To allow for inclusion of elements that are not defined by the
858                <literal>cansas1d.xsd</literal> XML
859                Schema, XML <emphasis role="italic">foreign elements</emphasis> 
860                <indexterm>
861                    <primary>XML</primary>
862                    <secondary>foreign elements</secondary>
863                </indexterm>
864                are permitted at select locations in the
865                cansas1d/1.1 format. Please refer to the section
866                <link xlink:href="#wiki-XML_Help"><emphasis>XML Help</emphasis></link>
867                 for more help with XML foreign elements. </para>
868            <para> 
869                There is an example that demonstrates the use of a foreign
870                namespace:<footnote>
871                    <para>
872                        <link
873                            xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/data/Glassy%20Carbon/ISIS/GLASSYC_C4G8G9_withTL.xml"
874                            ><literal
875                                >http://svn.smallangles.net/trac/canSAS/browser/1dwg/data/Glassy%20Carbon/ISIS/GLASSYC_C4G8G9_withTL.xml</literal></link></para>
876                </footnote>
877                This example uses a foreign namespace to record the transmission spectrum related to
878                the acquisition of the SANS data at a time-of-flight facility. Look near line 153
879                for this element:
880                <informalexample>
881                    <programlisting>&lt;transmission_spectrum xmlns="urn:transmission:spectrum"></programlisting>
882                </informalexample>
883                The foreign namespace given
884                (<literal>urn:transmission:spectrum</literal>) becomes the default namespace for just the
885                <literal>transmission_spectrum</literal> element. </para>
886            <para>Also refer to <link
887                xlink:href="http://svn.smallangles.net/trac/canSAS/changeset/47">canSAS TRAC
888                ticket #47</link> for an example of arranging the content in
889                <literal>SASprocessnote</literal> to avoid the use of foreign namespace
890                elements. </para>
891        </section>
892        <section xml:id="cansas1d_documentation-Support_Tools">
893            <title>Support tools for Visualization &amp; Analysis software</title>
894            <para> Support for importing cansas1d/1.1 files exists for these
895                languages and environments:
896            </para>
897            <itemizedlist>
898                <listitem>
899                    <para>
900                        <emphasis role="bold">FORTRAN</emphasis>:
901                        See the section titled
902                        <link xlink:href="#cansas1d_documentation-binding-Fortran"
903                            ><emphasis role="italic">Fortran binding</emphasis></link>.
904                        <indexterm>
905                            <primary>binding</primary>
906                            <secondary>FORTRAN</secondary>
907                        </indexterm>
908                        <indexterm>
909                            <primary>FORTRAN</primary>
910                            <see>binding, FORTRAN</see>
911                        </indexterm>
912                    </para>
913                </listitem>
914                <listitem>
915                    <para>
916                        <emphasis role="bold">IgorPro</emphasis>:
917                        See the section titled
918                        <link xlink:href="#cansas1d_documentation-binding-IgorPro"
919                            ><emphasis role="italic">IgorPro binding</emphasis></link>.
920                        <indexterm>
921                            <primary>binding</primary>
922                            <secondary>IgorPro</secondary>
923                        </indexterm>
924                        <indexterm>
925                            <primary>IgorPro</primary>
926                            <see>binding, IgorPro</see>
927                        </indexterm>
928                    </para>
929                </listitem>
930                <listitem>
931                    <para>
932                        <emphasis role="bold">Java</emphasis>:
933                        See the section titled
934                        <link xlink:href="#cansas1d_documentation-binding-Java"
935                            ><emphasis role="italic">Java JAXB binding</emphasis></link>.
936                        <indexterm>
937                            <primary>binding</primary>
938                            <secondary>Java</secondary>
939                        </indexterm>
940                        <indexterm>
941                            <primary>Java</primary>
942                            <see>binding, Java</see>
943                        </indexterm>
944                    </para>
945                </listitem>
946                <listitem>
947                    <para>
948                        <emphasis role="bold">Microsoft Excel</emphasis>:
949                        Support for Microsoft Excel
950                        <indexterm>
951                            <primary>binding</primary>
952                            <secondary>Microsoft Excel</secondary>
953                        </indexterm>
954                        <indexterm>
955                            <primary>Microsoft Excel</primary>
956                            <see>binding, Microsoft Excel</see>
957                        </indexterm>
958                        is provided through the default canSAS stylesheet <link
959                            xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansasxml-html.xsl"
960                            >cansasxml-html.xsl</link>.
961                        The <link
962                            xlink:href="http://www.isis.stfc.ac.uk/instruments/loq/loq2470.html"
963                            >ISIS LOQ instrument</link> has provided an <link
964                                xlink:href="http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/xml/cansas_xml_format.pdf"
965                                >excellent description</link><footnote><para><link
966                            xlink:href="http://www.isis.stfc.ac.uk/instruments/loq/loq2470.html"
967                            ><literal>http://www.isis.stfc.ac.uk/instruments/loq/loq2470.html</literal
968                            ></link></para></footnote>
969                        of how to import data from the
970                        cansas1d/1.1 format into Excel.
971                        Also note that the
972                            <link
973                            xlink:href="http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/loq.htm">old
974                            WWW site</link><footnote><para><link
975                            xlink:href="http://www.isis.rl.ac.uk/LargeScale/LOQ/loq.htm"
976                            ><literal>http://www.isis.rl.ac.uk/LargeScale/LOQ/loq.htm</literal
977                            ></link></para></footnote>
978                        may still be available.
979                    </para>
980                </listitem>
981                <listitem>
982                    <para>
983                        <emphasis role="bold">PHP</emphasis>:
984                        The <link xlink:href="#cansas1d_documentation-converting_into_XML"
985                            ><emphasis role="italic">canSAS/xmlWriter</emphasis></link>
986                        <indexterm><primary><literal>xmlWriter</literal></primary></indexterm>
987                        is implemented in <link xlink:href="http://www.php.net">PHP</link
988                        ><footnote><para><link xlink:href="http://www.php.net"
989                            ><literal>http://www.php.net</literal></link></para></footnote>
990                        <indexterm>
991                            <primary>binding</primary>
992                            <secondary>PHP</secondary>
993                        </indexterm>
994                        <indexterm>
995                            <primary>PHP</primary>
996                            <see>binding, PHP</see>
997                        </indexterm>
998                        and writes a cansas1d/1.1 data file given three-column ASCII data as input.
999                        (<link
1000                            xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/php/xmlWriter/index.php"
1001                            >PHP source</link>)<footnote>
1002                            <para>
1003                                <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/php/xmlWriter/index.php"
1004                                    ><literal>http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/php/xmlWriter/index.php</literal></link>
1005                            </para>
1006                        </footnote>
1007                        The code uses <link xlink:href="http://www.php.net/DomDocument">DomDocument</link
1008                        ><footnote><para><link xlink:href="http://www.php.net/DomDocument"
1009                            ><literal>http://www.php.net/DomDocument</literal></link></para></footnote>
1010                        to build the XML file.  Look for the line beginning with
1011                        <literal>function prepare_cansasxml($post)</literal>.
1012                    </para>
1013                    <para>
1014                        Another example of <literal>DomDocument</literal>
1015                        is in the <literal>function surveillance($post)</literal> where
1016                        logging information is inserted into an XML file.
1017                    </para>
1018                </listitem>
1019                <listitem>
1020                    <para>
1021                        <emphasis role="bold">Python</emphasis>:
1022                        See the section titled
1023                        <link xlink:href="#cansas1d_documentation-binding-Python"
1024                            ><emphasis role="italic">Python binding</emphasis></link>.
1025                        <indexterm>
1026                            <primary>binding</primary>
1027                            <secondary>Python</secondary>
1028                        </indexterm>
1029                        <indexterm>
1030                            <primary>Python</primary>
1031                            <see>binding, Python</see>
1032                        </indexterm>
1033                    </para>
1034                </listitem>
1035                <listitem>
1036                    <para>
1037                        <emphasis role="bold">XSLT</emphasis> (useful in a web browser)
1038                        is described later in the section titled
1039                        <link xlink:href="#xml-stylesheet"><emphasis role="italic">Example XML Stylesheets</emphasis></link>.
1040                        <indexterm>
1041                            <primary>binding</primary>
1042                            <secondary>XML Stylesheet (XSLT)</secondary>
1043                        </indexterm>
1044                    </para>
1045                </listitem>
1046            </itemizedlist>
1047        </section>
1048        <section xml:id="cansas1d_documentation-repositories">
1049            <title>Software repositories (for cansas1d/1.1 standard)</title>
1050            <itemizedlist>
1051                <listitem>
1052                    <para><emphasis role="bold">TRAC</emphasis>: <link
1053                            xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/tags/v1.0"
1054                            ><literal>http://svn.smallangles.net/trac/canSAS/browser/1dwg/tags/v1.0</literal></link></para>
1055                </listitem>
1056                <listitem>
1057                    <para><emphasis role="bold">Subversion</emphasis>: <link
1058                            xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0"
1059                            ><literal>http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0</literal></link></para>
1060                </listitem>
1061            </itemizedlist>
1062        </section>
1063    </section>
1064    <section xml:id="cansas1d_documentation-schema_validation">
1065        <title>Validation of XML against the Schema</title>
1066        <indexterm>
1067            <primary>validation</primary>
1068            <secondary>against XML Schema</secondary>
1069        </indexterm>
1070        <orderedlist>
1071            <listitem>
1072                <para>open browser to:
1073                    <link xlink:href="http://www.xmlvalidation.com/"
1074                        ><literal>http://www.xmlvalidation.com/</literal></link></para>
1075            </listitem>
1076            <listitem>
1077                <para>paste content of candidate XML file (with reference in the header to the XML
1078                    Schema as shown above) into the form</para>
1079            </listitem>
1080            <listitem>
1081                <para>press <literal>&lt;validate></literal></para>
1082            </listitem>
1083            <listitem>
1084                <para>paste content of
1085                    <literal>cansas1d.xsd</literal><footnote><para><link
1086                        xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"
1087                        ><literal>http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd</literal
1088                    ></link></para></footnote>
1089                    XSD file into form and press <literal>&lt;continue validation></literal>.</para>
1090            </listitem>
1091            <listitem>
1092                <para>check the results</para>
1093            </listitem>
1094        </orderedlist>
1095    </section>
1096</chapter>
Note: See TracBrowser for help on using the repository browser.