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

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

manual is nearly complete for v1.0 release, still a few problems to resolve (table+figure, code examples), refs #19

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