source: 1dwg/trunk/IgorPro/readme.wiki @ 42

Last change on this file since 42 was 42, checked in by prjemian, 13 years ago

describe better what the IgorPro? XML reader does and how the data is structured in IgorPro?

File size: 12.1 KB
Line 
1= canSAS 1-D SAS XML format binding to IgorPro =
2 
3An import tool (binding) for IgorPro has been created (cansasXML.ipf).
4You can check out the IgorPro working directory from the SVN server (see 
5[[#Checkout_of_support_code_in_Subversion | instructions below]]).
6
7To use the canSASxml.ipf procedure, you must have the XMLutils XOP
8IGOR plugin installed.  See the [[#Usage_Notes | Usage Notes]] below.
9
10Note that the code described here is ''not a complete user interface''.
11(See further comments [[#List_of_Functions | below]].)
12It is expected that this code will be called by a graphical user interface routine
13and that routine will handle the work of copying the loaded SAS data in
14IgorPro from the <nowiki>root:Packages:CS_XMLreader</nowiki> data folder to the destination
15of choice (including any renaming of waves as desired).
16
17{| {{Tablestyle}}
18|-
19! {{Headcellstyle}} | file
20|| [http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/IgorPro/cansasXML.ipf cansasXML.ipf]
21|-
22! {{Headcellstyle}} | author
23|| Pete R. Jemian <jemian@anl.gov>
24|-
25! {{Headcellstyle}} | date
26|| 2008-05-19
27|-
28! {{Headcellstyle}} | version
29|| 1.07  ('''requires''' latest XMLutils XOP -- see below)
30|-
31! {{Headcellstyle}} | purpose
32|| implement an IgorPro file reader to read the canSAS 1-D reduced SAS data in XML files <br /> adheres to the cansas1d/1.0 standard:  http://www.smallangles.net/wgwiki/index.php/cansas1d_documentation
33|-
34! {{Headcellstyle}} | URL
35||      TRAC: http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/IgorPro/cansasXML.ipf <br /> SVN: http://svn.smallangles.net/svn/canSAS/1dwg/trunk/IgorPro/cansasXML.ipf
36|-
37! {{Headcellstyle}} | requires
38|| IgorPro: http://www.wavemetrics.com <br /> XMLutils - XOP: http://www.igorexchange.com/project/XMLutils (IGOR.5.04.x-1.x-dev, 2008-May-19)
39|-
40|}
41
42=== Checkout of support code in Subversion ===
43
44Subversion (http://subversion.tigris.org/) is a program for
45managing software versions.  There are command line and GUI clients
46for a variety of operating systems.  We won't recommend any here
47but will show the command lines necessary.
48
49==== XMLutils XOP ====
50
51The XMLutils XOP, written by Andrew Nelson (ANSTO), is hosted
52on the IgorExchange (http://www.igorexchange.com/).
53
54One good location to place the checked out XMLutils directory
55is in the Wavemetrics directory, next to the <nowiki>Igor Pro Folder</nowiki>
56<pre>svn://svn.igorexchange.com/packages/XMLutils/ XMLutils</pre>
57
58In the future, to retrieve an updated version of this support, go into
59the <nowiki>XMLutils</nowiki> directory (created above) and type the command
60<pre>svn update</pre>
61This will check the repository and update files as needed.
62If the installer program was updated, you;ll need to run the new
63installer program.  It is not necessary to uninstall first.
64
65The installer executables contained in the download will
66do all the installation for you.  They will place the XOP in the folder
67''/User Procedures/motofit/XMLutils'', and create a shortcut/alias to the
68plugin in /Igor Extensions.
69Packages from other facilities should place the XOP there as well.
70
71==== cansasXML.ipf ====
72
73Check out the canSAS 1d SAS XML reader from the subversion repository:
74<pre>svn checkout http://svn.smallangles.net/svn/canSAS/1dwg/trunk cansas-1dwg</pre>
75
76This will download lots of extra files.  The file of interest is in the <nowiki>IgorPro</nowiki>
77directory and is called <nowiki>cansasXML.ipf</nowiki>
78
79In the future, to retrieve an updated version of this support, go into
80the <nowiki>cansas-1dwg</nowiki> directory (created above) and type the command
81<pre>svn update</pre>
82This will check the repository and update files as needed.
83
84==  Installation  ==
85
86# License and Install IgorPro (should have already been done by now)
87# Quit IgorPro if it is running
88# Download XMLutils XOP.  Either checkout from subversion (see above) or, with a web browser, go to http://svn.igorexchange.com/viewvc/packages/XMLutils/trunk/
89# Install XMLutils XOP by double-clicking the installer for you operating system.
90# Download cansasXML.ipf.  Either checkout from subversion (see above) or, with a web browser, copy cansasXML.ipf from on-line subversion repository: http://svn.smallangles.net/svn/canSAS/1dwg/trunk/IgorPro/cansasXML.ipf
91# Copy cansasXML.ipf file to <nowiki>...\Wavemetrics\Igor Pro Folder\User Procedures</nowiki> (or file system equivalent)
92# Then, you should be able to restart IgorPro and progress from there
93
94==  Usage Notes  ==
95
96To use the canSASxml.ipf procedure, you must have the XMLutils XOP
97IGOR plugin installed. This may be downloaded from the IgorExchange
98Project site. There are installer executables contained in the
99download that will do all the installation for you. Each installer will place
100the XOP in the folder
101<nowiki>...\Wavemetrics\Igor Pro Folder\User Procedures\motofit\XMLutils</nowiki>,
102and create
103a shortcut/alias to the plugin in
104<nowiki>...\Wavemetrics\Igor Pro Folder\Igor Extensions</nowiki>.
105
106== What it does ==
107
108Given an XML file, '''CS_XmlReader(fileName)''' attempts to open the file
109and read its contents as if it conformed to the canSAS XML standard for
110reduced 1-D SAS data (cansas1d/1.0, also known as SASXML).  If the file is
111found to be non-conforming, then '''CS_XmlReader(fileName)''' returns with an
112error code (show below), otherwise it returns '''0''' that indicates ''no error''.
113All data read by this code is left in the IgorPro data folder
114'''''root:Packages:CS_XMLreader''''' for pickup by the calling routine.
115(Two examples are provided to show how a routine might retrieve the data.)
116
117After opening the XML file (with a file identifier ''fileID''), control is
118passed to '''CS_1i_parseXml(fileID)''' which then walks through the XML
119elements.  For each '''SASentry''' in the file, a new data folder is created
120with the name derived from the Title element (or best effort determination).
121Efforts are taken to avoid duplication of data folder names (using standard
122IgorPro routines).  For '''SASentry''' elements that contain  more than one SASdata
123element, a '''SASdata''' folder is created for each and the corresponding ''I(Q)''
124is placed in that subfolder.  When only one '''SASdata''' is found, the ''I(Q)''
125data is placed in the main ''Title'' folder.
126
127=== data columns ===
128
129Each column of data in the '''SASdata/Idata/*''' table is placed into a single
130IgorPro wave.  At present, the code does not check for non-standard data columns.
131(The capability is built into the code but is deactivated at present).
132
133=== metadata ===
134
135Additional metadata is collected into a single text wave (''metadata'') where the first column
136is an identifier (or ''key'') and the second identifier is the ''value''.  Only
137those keys with non-empty values are retained in the metadata table.
138'''CAUTION:''' The ''values'' are not checked for characters that may cause trouble when
139placed in a wave note.  This will be the responsibility of the calling routine
140to ''clean these up'' if the need arises.
141
142The code checks for most metadata elements and will check for repeated elements
143where the standard permits.
144
145Here is an example of the metadata for the [[cansas1d_casestudy_collagen | ''cs_collagen_full.xml'']] data:
146
147{| {{Tablestyle}}
148|-
149! {{Headcellstyle}} | ''i'' (''row'')
150! {{Headcellstyle}} | metadata[''i''][0] (''key'')
151! {{Headcellstyle}} | metadata[''i''][1] (''value'')
152|-
153|| 0
154|| xmlFile
155|| cs_collagen_full.xml
156|-
157|| 1
158|| namespace
159|| cansas1d/1.0
160|-
161|| 2
162|| Title
163|| dry chick collagen, d = 673 A, 6531 eV, X6B
164|-
165|| 3
166|| Run
167|| Sep 19 1994     01:41:02 am
168|-
169|| 4
170|| SASsample/ID
171|| dry chick collagen, d = 673 A, 6531 eV, X6B
172|-
173|| 5
174|| SASinstrument/name
175|| X6B, NSLS, BNL
176|-
177|| 6
178|| SASinstrument/SASsource/radiation
179|| X-ray synchrotron
180|-
181|| 7
182|| SASinstrument/SASsource/wavelength
183|| 1.898
184|-
185|| 8
186|| SASinstrument/SASsource/wavelength/@unit
187|| A
188|-
189|| 9
190|| SASinstrument/SASdetector/@name
191|| X6B PSD
192|-
193|| 10
194|| SASnote
195|| <pre>Sep 19 1994     01:41:02 am     Elt: 00090 Seconds
196ID: No spectrum identifier defined
197Memory Size: 8192 Chls  Conversion Gain: 1024  Adc Offset: 0000 Chls
198
199dry chick collagen, d = 673 A
2006531 eV, X6B</pre>
201|-
202|}
203
204=== XML foreign namespace elements ===
205
206These are ignored at this time.
207
208=== XML namespace and header ===
209
210The routine does a ''best-efforts'' check to ensure that the given
211XML file conforms to the [[cansas1d_documentation#Required_XML_file_header |
212required XML file header]].  If you take a minimalist view (''a.k.a.'' a shortcut),
213it is likely that your file may be refused by this and other readers. 
214Pay particular attention to
215UPPER/lower case in the text '''cansas1d/1.0''' as this is a '''key component''' used to
216index through the XML file.
217
218==  List of Functions  ==
219
220These are (most of) the FUNCTIONS in the cansasXML.ipf code.
221The only functions of interest are '''CS_XmlReader(fileName)'''
222which reads the named XML file and and loads SAS data and the two demonstration
223functions '''prj_grabMyXmlData()''' and '''prjTest_cansas1d()'''
224that together show a usage example.
225
226;'''CS_XmlReader(fileName)''': open a canSAS 1-D reduced SAS XML data file
227*input: ''fileName'' (string) name of canSAS XML file (can include file system path name to file)
228*returns:
229**0 successful
230**-1: XML file not found
231**-2: root element is not <SASroot> with valid canSAS namespace
232**-3: <SASroot> version  is not 1.0
233**-4: no <SASentry> elements (NOT USED NOW)
234**-5: XOPutils needs upgrade
235;CS_1i_parseXml(fileID): '''This is what guides the work''', given a file ID returned from '''XMLOpenFile()''', parses that file for SAS data and metadata <br /> (1i in the function name signifies this is a function that supports INPUT from version 1.0 XML files)
236;CS_1i_getOneSASdata(fileID, Title, SASdataPath): harvest the data and metadata in the specific SASdata element
237;CS_1i_getOneVector(file,prefix,XML_name,Igor_name): harvest just one column (vector) of data
238;CS_1i_GetReducedSASdata(fileID, SASdataPath): grab the data and put it in the working data folder
239;CS_1i_locateTitle(fileID, SASentryPath): determine the title for this experiment
240;CS_appendMetaData(fileID, key, xpath, value): queries XML file for '''xpath'''.  If '''value''' is not empty, appends it to '''metadata''' where ''last'' is the new last row: <nowiki>metadata[last][0]=key; metadata[last][1]=value</nowiki>
241;CS_buildXpathStr(prefix, value): this function can be used only with very simple XPath constructions
242;CS_cleanFolderName(proposal): given a proposal string, returns a candidate folder name for immediate use
243;CS_findElementIndex(matchStr): looks for element index in structure ''W_ElementList'' returned from call to '''XmlElemList(fileID)'''
244;CS_getDefaultNamespace(fileID): returns the string containing the default namespace for the XML file
245;CS_registerNameSpaces(): Builds a table of all namespaces used in the XML file and appends '''W_ElementList''' with full namespace-xpath string for each element.
246;CS_simpleXmlListXpath(fileID, prefix, value): Calls '''XMLlistXpath()''' with proper namespace prefix attached.
247;CS_simpleXmlWaveFmXpath(fileID, prefix, value): Calls '''XMLwaveFmXpath()''' with proper namespace prefix attached.
248;CS_updateWaveNote(wavName, key, value): adds (or replaces) definition of ''key''=''value'' in the wave note of ''wavName''
249;CS_XmlStrFmXpath(fileID, prefix, value): Calls '''XmlStrFmXpath()''' with proper namespace prefix attached.  Trims the result string.
250;CS_XPath_NS(simpleStr): this function adds namespace info as necessary to simpleStr (an XPath)
251;TrimWS(str): Calls '''TrimWSL(TrimWSR(str))'''
252;TrimWSL(str): Trims white space from left (leading) end of '''str'''
253;TrimWSR(str): Trims white space from right (trailing) end of '''str'''
254;prjTest_cansas1d(): Demonstration function that calls '''CS_XmlReader(fileName)''' for many of the test data sets.
255;prj_grabMyXmlData(): Demonstration function that moves loaded data from <nowiki>root:Packages:CS_XMLreader</nowiki> to a user's data folder.  (In this ''example'', that folder is <nowiki>root:PRJ_canSAS</nowiki>.)
256;testCollette(): Demonstration function that reads an ISIS/LOQ file and copies the data to the root folder a la COLLETE
Note: See TracBrowser for help on using the repository browser.