source: 1dwg/trunk/doc/src/cansas1d_casestudy_collagen.xml @ 138

Last change on this file since 138 was 138, checked in by prjemian, 11 years ago

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

  • Property svn:executable set to *
  • Property svn:keywords set to Date Revision Author HeadURL Id
File size: 11.1 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<!-- from: http://www.smallangles.net/wgwiki/index.php/cansas1d_SASroot -->
13<section xml:id="cansas1d_documentation-case_study-collagen" xmlns="http://docbook.org/ns/docbook"
14    version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink">
15    <title>Case Study: Dry Chick Collagen</title>
16    <bridgehead> $Revision$ $Date$ </bridgehead>
17    <section>
18        <title>Overview</title>
19        <para> To demonstrate how to get SAS data into the XML standard format, consider this set of
20            SAXS data collected at the National Synchrotron Light Source, Brookhaven National
21            Laboratory, using a SAXS camera set up temporarily at beam line X6B (operated by the
22            Materials Science Division, Argonne National Lab). </para>
23        <para> The sample was <emphasis role="bold">dry chick collagen.</emphasis> (Thanks to
24            Malcolm Capel, NSLS beam line X12C for the sample.) </para>
25        <para>
26            <table>
27                <title>Figures for dry chick collagen case study</title>
28                <tgroup cols="2">
29                    <tbody>
30                        <row>
31                            <entry>
32                                <mediaobject>
33                                    <imageobject>
34                                        <imagedata
35                                            fileref="../../graphics/cs-collagen-data-table-Excel.jpg"
36                                            width="200pt" scalefit="1"/>
37                                    </imageobject>
38                                    <caption>
39                                        <para>case study: Collagen, SAXS data in Excel table</para>
40                                    </caption>
41                                </mediaobject>
42                            </entry>
43                            <entry>
44                                <mediaobject>
45                                    <imageobject>
46                                        <imagedata
47                                            fileref="../../graphics/cs-collagen-saxs-chart-excel.jpg"
48                                            width="200pt" scalefit="1"/>
49                                    </imageobject>
50                                    <caption>
51                                        <para>case study: Collagen, SAXS data in Excel chart</para>
52                                    </caption>
53                                </mediaobject>
54                            </entry>
55                        </row>
56                    </tbody>
57                </tgroup>
58            </table>
59        </para>
60        <para> The raw data was collected on a linear position-sensitive detector and reduced to
61            columns of <emphasis role="bold">Q</emphasis>, <emphasis role="bold">I</emphasis>, and
62                <emphasis role="bold">Iesd</emphasis> (estimated standard deviation of <emphasis
63                role="bold">I</emphasis>). </para>
64        <para> The only metadata available for this data (without resorting to digging through piles
65            of old notebooks) was obtained from two file headers: </para>
66        <para>
67            <link
68                xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/collagen/COLLAGEN.ASC">
69                <citetitle>collagen.asc</citetitle>
70            </link>
71            <programlisting>Sep 19 1994     01:41:02 am     Elt: 00090 Seconds
72ID: No spectrum identifier defined
73Memory Size: 8192 Chls  Conversion Gain: 1024  Adc Offset: 0000 Chls        </programlisting>
74        </para>
75        <para>
76            <link
77                xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/collagen/collagen.saxs">
78                <citetitle>collagen.saxs</citetitle>
79            </link>
80            <programlisting>dry chick collagen, d = 673 A
816531 eV, X6B</programlisting>
82        </para>
83        <para> But, the data can fulfill the minimum requirements of the 1D standard file format and
84            also make an excellent example of a minimal canSAS reduced 1-D SAS data file in XML.
85        </para>
86    </section>
87    <section>
88        <title>Procedure</title>
89        <section>
90            <title>make the basic XML file</title>
91            <para> It is easiest to copy a template rather than start from an empty file. Copy the
92                    <link xlink:href="http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xml">
93                    <citetitle>cansas1d.xml</citetitle>
94                </link> file into your working directory and rename it to <emphasis role="bold"
95                    >collagen.xml</emphasis>. </para>
96        </section>
97        <section>
98            <title>modify collagen.xml</title>
99            <para> It is easier to see the metadata in the XML file before you enter the SAXS data
100                into the file. With the brief metadata available, most lines can be eliminated. This
101                will result in a file that looks like </para>
102            <programlisting>&lt;?xml version="1.0"?>
103&lt;?xml-stylesheet type="text/xsl" href="example.xsl" ?>
104&lt;SASroot version="1.0"
105    xmlns="cansas1d/1.0"
106    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
107    xsi:schemaLocation="cansas1d/1.0 http://svn.smallangles.net/svn/canSAS/1dwg/trunk/cansas1d.xsd"
108    >
109    &lt;SASentry>
110    &lt;Title>dry chick collagen, d = 673 A, 6531 eV, X6B&lt;/Title>
111        &lt;Run />
112        &lt;SASdata>
113            &lt;!-- Idata lines will go here -->
114        &lt;/SASdata>
115        &lt;SASsample>
116            &lt;ID>dry chick collagen, d = 673 A, 6531 eV, X6B&lt;/ID>
117        &lt;/SASsample>
118        &lt;SASinstrument>
119            &lt;name>X6B, NSLS, BNL&lt;/name>
120            &lt;SASsource>
121                &lt;radiation>X-ray synchrotron&lt;/radiation>
122                &lt;wavelength unit="A">
123                    1.898
124                    &lt;!-- = 12398/6531 -->
125                &lt;/wavelength>
126            &lt;/SASsource>
127            &lt;SAScollimation />
128            &lt;SASdetector>
129                &lt;name>X6B PSD&lt;/name>
130            &lt;/SASdetector>
131        &lt;/SASinstrument>
132        &lt;SASnote>
133            Sep 19 1994     01:41:02 am     Elt: 00090 Seconds
134            ID: No spectrum identifier defined
135            Memory Size: 8192 Chls  Conversion Gain: 1024  Adc Offset: 0000 Chls
136           
137            dry chick collagen, d = 673 A
138            6531 eV, X6B
139        &lt;/SASnote>
140    &lt;/SASentry>
141&lt;/SASroot></programlisting>
142        </section>
143        <section>
144            <title>prepare the SAXS data</title>
145            <para> Microsoft Excel is used here to convert the table of SAXS data into the required
146                lines of XML for the standard. Some may prefer to use a cell formula but here, we
147                develop a bit of Excel Macro code to clarify our procedure. </para>
148            <section>
149                <title>Excel macros used</title>
150                <para> Within Excel, with the SAXS data in columns as shown in the Excel table
151                    above, let's define the macros for our use. In Excel, type <emphasis role="bold"
152                        >&lt;alt>&lt;F11></emphasis> to open the macro editing window. </para>
153                <programlisting>Function XML_tag(tag, attr, content) As String
154  If attr = "" Then
155    XML = "&lt;" &amp; tag &amp; ">"
156  Else
157  XML = "&lt;" &amp; tag &amp; " " &amp; attr &amp; ">"
158  End If
159  XML = XML &amp; content
160  XML = XML &amp; "&lt;/" &amp; tag &amp; ">"
161  XML_tag = XML
162End Function
163
164Function SAS_Idata_tag(element, unit, content) As String
165XML = XML_tag(element, "unit=""" &amp; unit &amp; """", content)
166  SAS_Idata_tag = XML
167End Function
168
169Function Idata_tag(Q, Q_unit, I, I_unit, Idev, Idev_unit) As String
170  XML = SAS_Idata_tag("Q", Q_unit, Q)
171  XML = XML &amp; SAS_Idata_tag("I", I_unit, I)
172  XML = XML &amp; SAS_Idata_tag("Idev", Idev_unit, Idev)
173  Idata_tag = XML_tag("Idata", "", XML)
174End Function</programlisting>
175                <para> Your window will look similar to this one when you copy/paste the above code:
176                     (Yes, my spreadsheet is called MyFirstMacro.xls) </para>
177                <mediaobject>
178                    <imageobject>
179                        <imagedata fileref="../../graphics/cs-collagen-macro-editing.jpg"
180                            width="400pt" scalefit="1"/>
181                    </imageobject>
182                    <textobject>
183                        <phrase>case study: Collagen, SAXS data in Excel chart</phrase>
184                    </textobject>
185                    <caption>
186                        <para>case study: Collagen, SAXS data in Excel chart</para>
187                    </caption>
188                </mediaobject>
189                <para> Now close the macro editing window and return to the SAXS data in the
190                    spreadsheet. </para>
191            </section>
192            <section>
193                <title>construct the Idata lines in XML</title>
194                <para> move to spreadsheet cell <literal>E5</literal> and enter this
195                    formula <programlisting>=IDATA_tag(A5,$A$4,B5,$B$4,C5,$C$4)</programlisting>
196                </para>
197                <para> Copy it down all rows in column <emphasis role="bold">E</emphasis> through
198                    cell <literal>E335</literal>
199                </para>
200                <para> Select cells E5:E335 and copy to clipboard, then paste into
201                    <literal>collagen.xml</literal> document inside the
202                    <literal>SASdata</literal> element where you see the XML comment.
203                </para>
204            </section>
205        </section>
206    </section>
207    <section>
208        <title>Final Result</title>
209        <para> A nicely-formatted display version of the final result can be viewed through the TRAC
210            repository: <link
211                xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cs_collagen_full.xml">
212                <citetitle>http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cs_collagen_full.xml</citetitle>
213            </link>
214        </para>
215    </section>
216    <section>
217        <title>Validate your file</title>
218        <para> So you think you have an XML file. Let's validate it using the procedure from the
219            documentation.All the instructions are on the documentation page. No sense in repeating
220            them here. </para>
221    </section>
222    <section>
223        <title>References</title>
224        <para> All files are available at <link
225                xlink:href="http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/collagen/">
226                <citetitle>http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/examples/collagen/</citetitle>
227            </link>
228        </para>
229    </section>
230</section>
231
Note: See TracBrowser for help on using the repository browser.