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

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

move the "elements" section, rename "definitions of terms" to "glossary," more cross-references, formatting, & indices, refs #19

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