source: 1dwg/trunk/doc/src/wiki.xml @ 130

Last change on this file since 130 was 130, checked in by prjemian, 12 years ago

more cross-references, formatting, & indices, refs #19

  • Property svn:keywords set to Date Revision Author HeadURL Id
File size: 46.0 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>Wiki Manual</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 of the canSAS
19            <indexterm><primary>canSAS</primary></indexterm>
20            (Collective Action for Nomadic Small-Angle Scatterers)
21            forum of users, software developers, and facility staff was to discuss
22            better sharing of SAS data analysis software. <link
23                xlink:href="http://www.smallangles.net/canSAS">CanSAS</link>
24            <footnote><para>http://www.smallangles.net/canSAS</para></footnote>
25            identified that a significant need within the SAS
26            community can be satisfied by a robust, self-describing, text-based, standard format to
27            communicate reduced one-dimensional small-angle scattering data, ''I(Q)'', between users
28            of our facilities. Our goal has been to define such a format that leaves the data file
29            instantly human-readable, editable in the simplest of editors, and importable by simple
30            text import filters in programs that need not recognise advanced structure in the file
31            nor require advanced programming interfaces. The file should contain both the primary
32            data of ''I(Q)'' and also any other descriptive information (metadata) about the sample,
33            measurement, instrument, processing, or analysis steps. </para>
34        <para>The cansas1d/1.0
35            <indexterm><primary>cansas1d/1.0 standard</primary></indexterm> 
36            standard meets the objectives for a 1D standard, incorporating
37            metadata about the measurement, parameters and results of processing or analysis steps.
38            Even multiple measurements (related or unrelated) may be included within a single XML
39            file. </para>
40        <section xml:id="cansas1d_documentation_Objective-Status">
41            <title>Status</title>
42            <para>Version 1.0 was tagged from the subversion repository on 2009-05-12 as no changes
43                were committed since January 2009. Use this command to checkout the tagged release.
44                <programlisting>svn checkout http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0 cansas1dwg-1.0</programlisting></para>
45        </section>
46    </section>
47    <section xml:id="cansas1d_documentation-XMLLayout">
48        <title>General Layout of the XML Data</title>
49        <para>The canSAS 1-D standard for reduced 1-D SAS data is implemented using XML files. A
50            single file can contain SAS data from a single experiment or multiple experiments. All
51            types of relevant data (''I(Q)'', metadata) are described for each experiment. More
52            details are provided below.</para>
53        <section xml:id="cansas1d_documentation-XMLLayout-Overview">
54            <title>Overview</title>
55            <para>The basic elements of the cansas1d/1.0 standard are shown in the following table.
56                After an XML header, the root element of the file is
57                <link xlink:href="#cansas1d_documentation-element-SASroot"
58                    ><code>SASroot</code></link>
59                <indexterm><primary>SASroot</primary></indexterm>
60                which contains one or more
61                <link xlink:href="#cansas1d_documentation-element-SASentry"
62                    ><code>SASentry</code></link>
63                <indexterm><primary>SASentry</primary></indexterm>
64                elements, each of which
65                describes a single experiment (data set, time-slice, step in a series, new sample,
66                etc.). Details of the <literal>SASentry</literal> element are also shown in the
67                next figure.
68                <!--Refer to the [[cansas1d_block_diagrams | block diagrams]] for
69                alternative depictions.--> 
70                See <link
71                    xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml"
72                    >cansas1d.xml</link>
73                <footnote>
74                    <para>
75                        http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml
76                    </para>
77                </footnote>
78                for an example XML file. Examples, Case Studies, and other background information
79                are below. More discussion can be found on the
80                <link
81                    xlink:href="http://www.smallangles.net/wgwiki/index.php/1D_Data_Formats_Working_Group"
82                    >canSAS 1D Data Formats Working Group</link>
83                <footnote>
84                    <para>
85                        http://www.smallangles.net/wgwiki/index.php/1D_Data_Formats_Working_Group
86                    </para>
87                </footnote>
88                page and its
89                <link
90                    xlink:href="http://www.smallangles.net/wgwiki/index.php/Talk:1D_Data_Formats_Working_Group"
91                    >discussion</link>
92                <footnote>
93                    <para>
94                        http://www.smallangles.net/wgwiki/index.php/Talk:1D_Data_Formats_Working_Group
95                    </para>
96                </footnote>
97                page.  A
98                <link
99                    xlink:href="#cansas1d_documentation-Documentation-Definitions"
100                    >glossary</link>
101                <indexterm><primary>glossary</primary><see>definition of terms</see></indexterm>
102                defining the details about each specific field (XPath string, XML elements and attributes) is provided.
103                </para>
104            <figure>
105                <title>block diagram of minimum elements required for cansas1d/1.0 standard</title>
106                <mediaobject>
107                    <imageobject>
108                        <imagedata fileref="../../graphics/10-minimum.png" scalefit="1" width="200pt"/>
109                    </imageobject>
110                </mediaobject>
111            </figure>
112            <itemizedlist>
113                <listitem>
114                    <para> 
115                        <link xlink:href="#cansas1d_documentation-element-SASroot"
116                            ><literal>SASroot</literal></link>:
117                        the root element of the file (after the XML header)
118                    </para>
119                </listitem>
120                <listitem>
121                    <para> 
122                        <link xlink:href="#cansas1d_documentation-element-SASentry"
123                            ><literal>SASentry</literal></link>:
124                        describes a single experiment (data set, time-slice, step in a
125                        series, new sample, etc.)
126                    </para>
127                </listitem>
128                <listitem>
129                    <para> block diagrams </para>
130                </listitem>
131                <listitem>
132                    <para> cansas1d.xml example XML file </para>
133                </listitem>
134                <listitem>
135                    <para> discussion of this format: basic more </para>
136                </listitem>
137                <listitem>
138                    <para> Seek outside help for XML </para>
139                </listitem>
140                <listitem>
141                    <para> Definition of terms: Details about each specific field (XPath string, XML
142                        elements and attributes) </para>
143                </listitem>
144            </itemizedlist>
145            <section xml:id="cansas1d_documentation-Basic_elements">
146                <title>Basic elements of the cansas1d/1.0 standard</title>
147                <para>
148                    <table frame="all">
149                        <title>Basic elements of the CanSAS 1-D standard</title>
150                        <tgroup cols="2">
151                            <colspec colname="c1" colnum="1" colwidth="2*"/>
152                            <colspec colname="c2" colnum="2" colwidth="6*"/>
153                            <thead>
154                                <row>
155                                    <entry><?dblatex bgcolor="[gray]{0.8}"?>Element</entry>
156                                    <entry><?dblatex bgcolor="[gray]{0.8}"?>Description</entry>
157                                </row>
158                            </thead>
159                            <tbody>
160                                <row>
161                                    <entry>XML Header</entry>
162                                    <entry>descriptive info required at the start of every XML
163                                        file</entry>
164                                </row>
165                                <row>
166                                    <entry>
167                                        <emphasis role="bold">
168                                            <link xlink:href="#cansas1d_documentation-element-SASroot"
169                                                ><code>SASroot</code></link>
170                                        </emphasis>
171                                    </entry>
172                                    <entry>root element of XML file</entry>
173                                </row>
174                                <row>
175                                    <entry>
176                                        <emphasis role="bold">
177                                            <link xlink:href="#cansas1d_documentation-element-SASentry"
178                                                ><code>&#160;SASentry</code></link>
179                                        </emphasis>
180                                    </entry>
181                                    <entry>data set, time-slice, step in a series, new sample,
182                                        etc.</entry>
183                                </row>
184                                <row>
185                                    <entry>
186                                        <emphasis role="bold">
187                                            <code>&#160;&#160;Title</code>
188                                        </emphasis>
189                                    </entry>
190                                    <entry>for this particular <literal>SASentry</literal></entry>
191                                </row>
192                                <row>
193                                    <entry>
194                                        <emphasis role="bold">
195                                            <code>&#160;&#160;Run</code>
196                                        </emphasis>
197                                    </entry>
198                                    <entry>run number or ID number of experiment</entry>
199                                </row>
200                                <row>
201                                    <entry>
202                                        <emphasis role="bold">
203                                            <code>&#160;&#160;{any}</code>
204                                        </emphasis>
205                                    </entry>
206                                    <entry>any non-cansas1d/1.0 element can be used at this
207                                        point</entry>
208                                </row>
209                                <row>
210                                    <entry>
211                                        <emphasis role="bold">
212                                            <code>&#160;&#160;SASdata</code>
213                                        </emphasis>
214                                    </entry>
215                                    <entry>this is where the reduced 1-D SAS data is stored</entry>
216                                </row>
217                                <row>
218                                    <entry>
219                                        <emphasis role="bold">
220                                            <code>&#160;&#160;&#160;Idata</code>
221                                        </emphasis>
222                                    </entry>
223                                    <entry>a single data point in the dataset</entry>
224                                </row>
225                                <row>
226                                    <entry>
227                                        <emphasis role="bold">
228                                            <code>&#160;&#160;{any}</code>
229                                        </emphasis>
230                                    </entry>
231                                    <entry>any non-cansas1d/1.0 element can be used at this
232                                        point</entry>
233                                </row>
234                                <row>
235                                    <entry>
236                                        <emphasis role="bold">
237                                            <code>&#160;&#160;SASsample</code>
238                                        </emphasis>
239                                    </entry>
240                                    <entry>description of the sample</entry>
241                                </row>
242                                <row>
243                                    <entry>
244                                        <emphasis role="bold">
245                                            <code>&#160;&#160;SASinstrument</code>
246                                        </emphasis>
247                                    </entry>
248                                    <entry>description of the instrument</entry>
249                                </row>
250                                <row>
251                                    <entry>
252                                        <emphasis role="bold">
253                                            <code>&#160;&#160;&#160;SASsource</code>
254                                        </emphasis>
255                                    </entry>
256                                    <entry>description of the source</entry>
257                                </row>
258                                <row>
259                                    <entry>
260                                        <emphasis role="bold">
261                                            <code>&#160;&#160;&#160;SAScollimation</code>
262                                        </emphasis>
263                                    </entry>
264                                    <entry>description of the collimation</entry>
265                                </row>
266                                <row>
267                                    <entry>
268                                        <emphasis role="bold">
269                                            <code>&#160;&#160;&#160;SASdetector</code>
270                                        </emphasis>
271                                    </entry>
272                                    <entry>description of the detector</entry>
273                                </row>
274                                <row>
275                                    <entry>
276                                        <emphasis role="bold">
277                                            <code>&#160;&#160;SASprocess</code>
278                                        </emphasis>
279                                    </entry>
280                                    <entry>for each processing or analysis step</entry>
281                                </row>
282                                <row>
283                                    <entry>
284                                        <emphasis role="bold">
285                                            <code>&#160;&#160;SASnote</code>
286                                        </emphasis>
287                                    </entry>
288                                    <entry>anything at all</entry>
289                                </row>
290                            </tbody>
291                        </tgroup>
292                    </table>
293                </para>
294            </section>
295            <section xml:id="cansas1d_documentation-required_header">
296                <title>Required XML file header</title>
297                <programlisting>
298&lt;?xml version="1.0"?>
299&lt;?xml-stylesheet type="text/xsl" href="cansasxml-html.xsl" ?>
300&lt;SASroot version="1.0"
301    xmlns="cansas1d/1.0"
302    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
303    xsi:schemaLocation="cansas1d/1.0
304    http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"></programlisting>
305            </section>
306        </section>
307        <section xml:id="cansas1d_documentation-rules">
308            <title>Rules</title>
309            <orderedlist>
310                <listitem>
311                    <para> canSAS1d/1.0 XML data files will adhere to the standard if they can
312                        successfully
313                        <link xlink:href="cansas1d_documentation-schema_validation">validate</link>
314                        <indexterm>
315                            <primary>validation</primary>
316                            <secondary>against XML Schema</secondary>
317                        </indexterm>
318                        against the established XML Schema
319                        (<link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd"
320                            ><literal>cansas1d.xsd</literal></link>).</para>
321                </listitem>
322                <listitem>
323                    <para>
324                        <inlineequation>
325                            <mathphrase>
326                                <alt>
327                                    Q=(4 \pi / \lambda) \sin(\theta)
328                                </alt>
329                            </mathphrase>
330                        </inlineequation>
331                    </para>
332                    <para>where
333                        <inlineequation><mathphrase><alt>\lambda</alt></mathphrase></inlineequation> 
334                        is the wavelength of the radiation</para>
335                    <para>and 
336                        <inlineequation><mathphrase><alt>2\theta</alt></mathphrase></inlineequation>
337                        is the angle through which the detected radiation has been
338                        scattered.</para>
339                    <figure>
340                        <title>definition of Q geometry for small-angle scattering</title>
341                        <mediaobject>
342                            <imageobject>
343                                <imagedata fileref="../../graphics/Q-geometry.jpg" scalefit="1"
344                                    width="200pt"/></imageobject>
345                        </mediaobject>
346                    </figure>
347                </listitem>
348                <listitem>
349                    <para> units to be given in standard SI abbreviations (eg, m, cm, mm, nm, K)
350                        with the following exceptions: </para>
351                    <orderedlist numeration="loweralpha">
352                        <listitem>
353                            <para>um=micrometres</para>
354                        </listitem>
355                        <listitem>
356                            <para>C=celsius</para>
357                        </listitem>
358                        <listitem>
359                            <para>A=Angstroms</para>
360                        </listitem>
361                        <listitem>
362                            <para>percent=%.</para>
363                        </listitem>
364                        <listitem>
365                            <para>fraction</para>
366                        </listitem>
367                        <listitem>
368                            <para>a.u.=arbitrary units</para>
369                        </listitem>
370                        <listitem>
371                            <para>none=no units are relevant (such as dimensionless)</para>
372                        </listitem>
373                    </orderedlist>
374                </listitem>
375                <listitem>
376                    <para> where reciprocal units need to be quoted the format shall be
377                        "1/abbreviation"</para>
378                </listitem>
379                <listitem>
380                    <para> when raised to a power, use similar to "A^3" or "1/m^4" (and not "A3" or
381                        "A**3" or "m-4")</para>
382                </listitem>
383                <listitem>
384                    <para> 
385                        axes:
386                        <indexterm><primary>geometry</primary></indexterm>
387                    </para>
388                    <orderedlist numeration="loweralpha">
389                        <listitem>
390                            <para>z is along the flight path (positive value in the direction of the
391                                detector)</para>
392                        </listitem>
393                        <listitem>
394                            <para>x is orthogonal to z in the horizontal plane (positive values
395                                increase to the right when viewed towards the incoming
396                                radiation)</para>
397                        </listitem>
398                        <listitem>
399                            <para>y is orthogonal to z and x in the vertical plane (positive values
400                                increase upwards)</para>
401                        </listitem>
402                        <listitem>
403                            <figure>
404                                <title>definition of translation and orientation geometry as viewed
405                                    from the detector towards the source</title>
406                                <para>
407                                    <table>
408                                        <title/>
409                                        <tgroup cols="2">
410                                            <tbody>
411                                                <row>
412                                                    <entry>
413                                                        <mediaobject>
414                                                            <imageobject>
415                                                                <imagedata
416                                                                    fileref="../../graphics/translation-orientation-geometry.jpg"
417                                                                    width="200pt" scalefit="1"/>
418                                                            </imageobject>
419                                                            <caption>
420                                                                <para>as viewed from source</para>
421                                                            </caption>
422                                                        </mediaobject>
423                                                    </entry>
424                                                    <entry>
425                                                        <mediaobject>
426                                                            <imageobject>
427                                                                <imagedata
428                                                                    fileref="../../graphics/translation-orientation-geometry-2.jpg"
429                                                                    width="200pt" scalefit="1"/>
430                                                            </imageobject>
431                                                            <caption>
432                                                                <para>as viewed from detector</para>
433                                                            </caption>
434                                                        </mediaobject>
435                                                    </entry>
436                                                </row>
437                                            </tbody>
438                                        </tgroup>
439                                    </table>
440                                </para>
441                            </figure>
442                        </listitem>
443                    </orderedlist>
444                </listitem>
445                <listitem>
446                    <para>orientation (angles) describes one-axis rotations (rotations about
447                        multiple axes require more information): </para>
448                    <orderedlist numeration="loweralpha">
449                        <listitem>
450                            <para>roll is about z</para>
451                        </listitem>
452                        <listitem>
453                            <para>pitch is about x</para>
454                        </listitem>
455                        <listitem>
456                            <para>yaw is about y</para>
457                        </listitem>
458                    </orderedlist>
459                </listitem>
460                <listitem>
461                    <para> Unicode characters MUST NOT be used</para>
462                </listitem>
463                <listitem>
464                    <para> Binary data is not supported</para>
465                </listitem>
466            </orderedlist>
467            <para>
468            </para>
469        </section>
470        <section xml:id="cansas1d_documentation-geometry_compatibility">
471            <title>Compatibility of Geometry Definitions</title>
472            <para> Note: translation and orientation geometry used by canSAS are consistent with: </para>
473            <itemizedlist>
474                <listitem>
475                    <para>http://en.wikipedia.org/wiki/Cartesian_coordinate_system</para>
476                </listitem>
477                <listitem>
478                    <para>http://en.wikipedia.org/wiki/Right-hand_rule</para>
479                </listitem>
480                <listitem>
481                    <para>http://www.nexusformat.org/Coordinate_Systems</para>
482                </listitem>
483                <listitem>
484                    <para><literal>McStas</literal>: http://mcstas.risoe.dk/documentation/tutorial/node6.html</para>
485                </listitem>
486                <listitem>
487                    <para>http://webhost5.nts.jhu.edu/reza/book/kinematics/kinematics.htm</para>
488                </listitem>
489            </itemizedlist>
490            <para>The translation and orientation geometry definitions used here are different than
491                those used by <link xlink:href="http://www.nanotech.wisc.edu/shadow"><emphasis
492                        role="bold">SHADOW</emphasis></link>
493                <footnote><para>http://www.nanotech.wisc.edu/shadow</para></footnote>
494                where the <emphasis role="italic">y</emphasis> and <emphasis role="italic"
495                    >z</emphasis> axes are swapped and the direction of <emphasis role="italic"
496                    >x</emphasis> is changed.</para>
497        </section>
498        <section xml:id="cansas1d_documentation-converting_into_XML">
499            <title>Converting data into the XML format</title>
500            <para>The
501                <link xlink:href="http://www.smallangles.net/canSAS/xmlWriter/"
502                    ><emphasis role="italic"></emphasis>canSAS/xmlWriter</link>
503                <footnote>
504                    <para>
505                        http://www.smallangles.net/canSAS/xmlWriter/
506                    </para>
507                </footnote>
508                <indexterm><primary><literal>xmlWriter</literal></primary></indexterm>
509                is a WWW form
510                to translate three-column ASCII text data into the canSAS1d/1.0 XML
511                format. This form will help you in creating an XML file with all the required
512                elements in the correct places. The form requests the SAS data of Q, I, and Idev
513                (defined elsewhere on this page) and some basic metadata (title, run, sample info,
514                ...). Press the <code>&lt;nowiki>Submit&lt;/nowiki></code> button and you will receive a nicely
515                formatted WWW page with the SAS data. If you then choose "View page source" (from
516                one of your browser menus), you will see the raw XML of the canSAS1d/1.0 XML format
517                and you can copy/paste this into an XML file. </para>
518            <para>The SAS data that you paste into the form box is likely to be copied directly from
519                a 3-column ASCII file from a text editor. Line breaks are OK, they will be treated
520                as white-space as will tabs and commas. Do not be concerned that the data looks
521                awful in the form entry box, just check the result to see that it comes out
522                OK.</para>
523        </section>
524    </section>
525    <section xml:id="cansas1d_documentation-Documentation-Definitions">
526        <title>Documentation and Definitions</title>
527        <section xml:id="cansas1d_documentation-XML_Schema">
528            <title>XML Schema</title>
529            <para> The
530                <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd"
531                    ><literal>cansas1d.xsd</literal></link>
532                <link xlink:href="http://www.w3schools.com/xsd"
533                    >XML Schema</link>
534                <footnote><para><literal>http://www.w3schools.com/xsd</literal></para></footnote>
535                <indexterm><primary>XML Schema</primary></indexterm>
536                defines the rules for the XML file format
537                <footnote>
538                    <para>
539                        TRAC: <literal>
540                            http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd
541                        </literal>
542                    </para>
543                </footnote>
544                <footnote>
545                    <para>
546                        SVN: <literal>
547                            http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd
548                        </literal>
549                    </para>
550                </footnote>
551                and is used to
552                validate any XML file for adherence to the format. </para>
553        </section>
554        <section xml:id="cansas1d_documentation-XML_Stylesheets">
555            <title>XML Stylesheets</title>
556            <itemizedlist>
557                <listitem>
558                    <para><literal>cansasxml-html.xsl</literal>:
559                        XSLT stylesheets
560                        <footnote>
561                            <para>http://www.w3schools.com/xsl/</para>
562                        </footnote>
563                        can be used to extract metadata or to convert into another file format. The
564                        default canSAS stylesheet
565                        <link xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansasxml-html.xsl"
566                            >http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansasxml-html.xsl</link>
567                        should be copied into each folder with canSAS XML data
568                        file(s). It can be used to display the data in a supporting WWW browser
569                        (such as Firefox or Internet Explorer) or to import into Microsoft Excel
570                        (with the added XML support in Excel). (See the excellent write-up by Steve
571                        King, ISIS,
572                        <footnote>
573                            <para>
574                                <link xlink:href="http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/xml/cansas_xml_format.pdf"
575                                    ><literal>http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/xml/cansas_xml_format.pdf</literal></link>
576                            </para>
577                        </footnote>
578                        for an example.) By default, MS Windows binds <literal>*.xml</literal> files to start
579                        Internet Explorer. Double-clicking on a canSAS XML data file with the
580                        <literal>cansasxml-html.xsl</literal> (see above)
581                        stylesheet in the same directory will produce a
582                        WWW page with the SAS data and selected metadata.</para>
583                </listitem>
584                <listitem>
585                    <para>Suggestions for support software that writes canSAS1d/1.0 XML data
586                        files:</para>
587                    <itemizedlist>
588                        <listitem>
589                            <para>be sure to update to the latest SVN repository revision (command:
590                                    <code>svn update</code>) </para>
591                        </listitem>
592                        <listitem>
593                            <para>check the output directory to see if it contains the default XSLT
594                                file.</para>
595                        </listitem>
596                        <listitem>
597                            <para>copy the latest XSLT file to the output directory if
598                                either:</para>
599                            <itemizedlist>
600                                <listitem>
601                                    <para>the output directory contains an older revision</para>
602                                </listitem>
603                                <listitem>
604                                    <para>the output directory does not have the default XSLT
605                                        file</para>
606                                </listitem>
607                            </itemizedlist>
608                        </listitem>
609                        <listitem>
610                            <para>The most recent XSLT file can be identified by examining the file
611                                for the <literal>$ Revision: </literal> string. For example:
612                                <code># &#36;Revision: 111 $</code> is version 111. </para>
613                        </listitem>
614                    </itemizedlist>
615                </listitem>
616            </itemizedlist>
617        </section>
618        <section xml:id="cansas1d_documentation-examples">
619            <title>Examples and Case Studies</title>
620            <itemizedlist>
621                <listitem>
622                    <para>
623                        <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml"
624                            >http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xml</link>
625                        (basic example): Note that, for clarity, only one row of data is
626                        shown. This is probably a very good example to use as a starting point for
627                        creating XML files with a text editor.</para>
628                </listitem>
629                <listitem>
630                    <para>
631                        <link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/bimodal-test1.xml"
632                            >http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/bimodal-test1.xml</link>:
633                        Simulated SAS data to test size distribution calculation routines.</para>
634                </listitem>
635                <listitem>
636                    <para>
637                        <link xlink:href="http://www.smallangles.net/wgwiki/index.php/Glassy_Carbon_Round_Robin"
638                            >Glassy Carbon Round Robin</link>:
639                        <footnote><para>http://www.smallangles.net/wgwiki/index.php/Glassy_Carbon_Round_Robin</para></footnote>
640                        Glassy carbon
641                        samples measured at several facilities worldwide.</para>
642                </listitem>
643                <listitem>
644                    <para>SAXS data from
645                        <link xlink:href="#cansas1d_documentation-case_study-collagen"
646                            >dry chick collagen</link>
647                        illustrates the
648                        minimum information necessary to meet the requirements of the standard
649                        format</para>
650                </listitem>
651                <listitem>
652                    <para>SANS data from
653                        <link xlink:href="#cansas1d_documentation-case_study-af1410"
654                            >AF1410 steel</link>: SANS study using magnetic
655                        contrast variation (with multiple samples and multiple data sets for each
656                        sample), the files can be viewed from TRAC (no description yet):
657                        [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/
658                        http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/af1410/]</para>
659                </listitem>
660                <listitem>
661                    <para><link xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d-template.xml"
662                        >http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d-template.xml</link>:
663                        This is used to test all the rules in the XML
664                        Schema. This is probably not a very good example to use as a starting point
665                        for creating XML files with a text editor since it tests many of the
666                        special-case rules.</para>
667                </listitem>
668            </itemizedlist>
669            <section xml:id="cansas1d_documentation-examples-multiple_experiments">
670                <title>XML layout for multiple experiments</title>
671                <para>Each experiment is described with a single '''SASentry''' element. The
672                    fragment below shows how multiple experiments can be included in a single XML
673                    file. Full examples of canSAS XML files with multiple experiments
674                    include:</para>
675                <itemizedlist>
676                    <listitem>
677                        <para> ISIS LOQ SANS instrument: <link
678                                xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/W1W2.XML"
679                                >http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/W1W2.XML</link>
680                        </para>
681                    </listitem>
682                    <listitem>
683                        <para> AF1410 steel SANS contrast variation study from NIST: <link
684                                xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/examples/af1410/cs_af1410.xml"
685                                >
686                                http://svn.smallangles.net/svn/canSAS/1dwg/trunk/examples/af1410/cs_af1410.xml
687                            </link>
688                        </para>
689                    </listitem>
690                </itemizedlist>
691                <para>Here is a brief sketch of how a file would be arranged with multiple SASentry
692                    elements and multiple SASdata elements.
693                    <programlisting language="xml" linenumbering="numbered">
694                        <textobject>
695                            <textdata fileref="brief-sketch-multiple.xml"/>
696                        </textobject>
697                    </programlisting>
698                </para>
699            </section>
700        </section>
701        <section xml:id="cansas1d_documentation-Foreign_Elements">
702            <title>Foreign Elements</title>
703            <para> To allow for inclusion of elements that are not defined by the cansas1d.xsd XML
704                Schema, XML <emphasis role="italic">foreign elements</emphasis> 
705                <indexterm>
706                    <primary>XML</primary>
707                    <secondary>foreign elements</secondary>
708                </indexterm>
709                are permitted at select locations in the
710                cansas1d/1.0 format. Please refer to the section
711                <link xlink:href="#wiki-XML_Help"><emphasis>XML Help</emphasis></link>
712                 for more help with XML foreign elements. </para>
713            <para> There is one example that demonstrates the use of a foreign namespace:
714                <footnote>
715                    <para>
716                        <link
717                            xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/data/Glassy%20Carbon/ISIS/GLASSYC_C4G8G9_withTL.xml"
718                            >http://svn.smallangles.net/trac/canSAS/browser/1dwg/data/Glassy%20Carbon/ISIS/GLASSYC_C4G8G9_withTL.xml</link>
719                    </para>
720                </footnote>
721                This example uses a foreign namespace to record the transmission spectra related to
722                the acquisition of the SANS data at a time-of-flight facility. Look for the
723                    <code>&lt;transmission_spectrum xmlns="urn:transmission:spectrum"></code>
724                element at line 153. The foreign namespace given
725                    (<literal>urn:transmission:spectrum</literal>) becomes the default for just the
726                    <literal>transmission_spectrum</literal> element. </para>
727            <para> Also refer to <link
728                    xlink:href="http://svn.smallangles.net/trac/canSAS/changeset/47">canSAS TRAC
729                    ticket #47</link> for an example of arranging the content in <emphasis
730                    role="bold">SASprocessnote</emphasis> to avoid the use of foreign namespace
731                elements. </para>
732        </section>
733        <section xml:id="cansas1d_documentation-Support_Tools">
734            <title>Support tools for Visualization &amp; Analysis software</title>
735            <para> Support for importing canSAS1d/1.0 files exists for these languages: <note>
736                    <para>Refactor the wiki pages here and link as appropriate.</para>
737                </note></para>
738            <itemizedlist>
739                <listitem>
740                    <para><emphasis role="bold">FORTRAN</emphasis></para>
741                </listitem>
742                <listitem>
743                    <para><emphasis role="bold">IgorPro</emphasis></para>
744                </listitem>
745                <listitem>
746                    <para><emphasis role="bold">Java</emphasis></para>
747                </listitem>
748                <listitem>
749                    <para>
750                        <emphasis role="bold">Microsoft Excel</emphasis> Support for Microsoft Excel
751                        is provided through the default canSAS stylesheet <link
752                            xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansasxml-html.xsl"
753                            >cansasxml-html.xsl</link>. An <link
754                            xlink:href="http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/xml/cansas_xml_format.pdf"
755                            >excellent description</link> of how to import data from the
756                        cansas1d/1.0 format into Excel is available from the <link
757                            xlink:href="http://www.isis.stfc.ac.uk/instruments/loq/loq2470.html"
758                            >ISIS LOQ instrument</link>.
759                        <footnote><para>http://www.isis.stfc.ac.uk/instruments/loq/loq2470.html</para></footnote>
760                        Also note that the
761                            <link
762                            xlink:href="http://www.isis.rl.ac.uk/archive/LargeScale/LOQ/loq.htm">old
763                            WWW site</link>
764                        <footnote><para>http://www.isis.rl.ac.uk/LargeScale/LOQ/loq.htm</para></footnote>
765                        may still be available. </para>
766                </listitem>
767                <listitem>
768                    <para><emphasis role="bold">PHP</emphasis></para>
769                </listitem>
770                <listitem>
771                    <para><emphasis role="bold">Python</emphasis></para>
772                </listitem>
773                <listitem>
774                    <para><emphasis role="bold">XSLT</emphasis> (useful in a web browser)</para>
775                </listitem>
776            </itemizedlist>
777        </section>
778        <section xml:id="cansas1d_documentation-repositories">
779            <title>Software repositories (for canSAS1d/1.0 standard)</title>
780            <itemizedlist>
781                <listitem>
782                    <para><emphasis role="bold">TRAC</emphasis>: <link
783                            xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/tags/v1.0"
784                            >http://svn.smallangles.net/trac/canSAS/browser/1dwg/tags/v1.0</link></para>
785                </listitem>
786                <listitem>
787                    <para><emphasis role="bold">Subversion</emphasis>: <link
788                            xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0"
789                            >http://svn.smallangles.net/svn/canSAS/1dwg/tags/v1.0</link></para>
790                </listitem>
791            </itemizedlist>
792        </section>
793    </section>
794    <section xml:id="cansas1d_documentation-schema_validation">
795        <title>Validation of XML against the Schema</title>
796        <orderedlist>
797            <listitem>
798                <para>open browser to: http://www.xmlvalidation.com/</para>
799            </listitem>
800            <listitem>
801                <para>paste content of candidate XML file (with reference in the header to the XML
802                    Schema as shown above) into the form</para>
803            </listitem>
804            <listitem>
805                <para>press &lt;validate></para>
806            </listitem>
807            <listitem>
808                <para>paste content of
809                    <link xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"
810                        ><literal>http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd</literal></link>
811                    XSD file into form and press <literal>&lt;continue validation></literal>.</para>
812            </listitem>
813            <listitem>
814                <para>check the results</para>
815            </listitem>
816        </orderedlist>
817    </section>
818</chapter>
Note: See TracBrowser for help on using the repository browser.