1 | = canSAS 1-D SAS XML format binding to IgorPro = |
---|
2 | |
---|
3 | An import tool (binding) for IgorPro has been created (cansasXML.ipf). |
---|
4 | You can check out the IgorPro working directory from the SVN server (see |
---|
5 | [[#Checkout_of_support_code_in_Subversion | instructions below]]). |
---|
6 | |
---|
7 | To use the canSASxml.ipf procedure, you must have the XMLutils XOP |
---|
8 | IGOR plugin installed. See the [[#Usage_Notes | Usage Notes]] below. |
---|
9 | |
---|
10 | Note that the code described here is ''not a complete user interface''. |
---|
11 | (See further comments [[#List_of_Functions | below]].) |
---|
12 | It is expected that this code will be called by a graphical user interface routine |
---|
13 | and that routine will handle the work of copying the loaded SAS data in |
---|
14 | IgorPro from the <nowiki>root:Packages:CS_XMLreader</nowiki> data folder to the destination |
---|
15 | of 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-03-31 |
---|
27 | |- |
---|
28 | ! {{Headcellstyle}} | purpose |
---|
29 | || 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 |
---|
30 | |- |
---|
31 | ! {{Headcellstyle}} | URL |
---|
32 | || 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 |
---|
33 | |- |
---|
34 | ! {{Headcellstyle}} | requires |
---|
35 | || IgorPro: http://www.wavemetrics.com <br /> XMLutils - XOP: http://www.igorexchange.com/project/XMLutils |
---|
36 | |- |
---|
37 | |} |
---|
38 | |
---|
39 | === Checkout of support code in Subversion === |
---|
40 | |
---|
41 | Subversion (http://subversion.tigris.org/) is a program for |
---|
42 | managing software versions. There are command line and GUI clients |
---|
43 | for a variety of operating systems. We won't recommend any here |
---|
44 | but will show the command lines necessary. |
---|
45 | |
---|
46 | ==== XMLutils XOP ==== |
---|
47 | |
---|
48 | The XMLutils XOP, written by Andrew Nelson (ANSTO), is hosted |
---|
49 | on the IgorExchange (http://www.igorexchange.com/). |
---|
50 | |
---|
51 | One good location to place the checked out XMLutils directory |
---|
52 | is in the Wavemetrics directory, next to the <nowiki>Igor Pro Folder</nowiki> |
---|
53 | <pre>svn://svn.igorexchange.com/packages/XMLutils/ XMLutils</pre> |
---|
54 | |
---|
55 | In the future, to retrieve an updated version of this support, go into |
---|
56 | the <nowiki>XMLutils</nowiki> directory (created above) and type the command |
---|
57 | <pre>svn update</pre> |
---|
58 | This will check the repository and update files as needed. |
---|
59 | If the installer program was updated, you;ll need to run the new |
---|
60 | installer program. It is not necessary to uninstall first. |
---|
61 | |
---|
62 | The installer executables contained in the download will |
---|
63 | do all the installation for you. They will place the XOP in the folder |
---|
64 | ''/User Procedures/motofit/XMLutils'', and create a shortcut/alias to the |
---|
65 | plugin in /Igor Extensions. |
---|
66 | Packages from other facilities should place the XOP there as well. |
---|
67 | |
---|
68 | ==== cansasXML.ipf ==== |
---|
69 | |
---|
70 | Check out the canSAS 1d SAS XML reader from the subversion repository: |
---|
71 | <pre>svn checkout http://svn.smallangles.net/svn/canSAS/1dwg/trunk cansas-1dwg</pre> |
---|
72 | |
---|
73 | This will download lots of extra files. The file of interest is in the <nowiki>IgorPro</nowiki> |
---|
74 | directory and is called <nowiki>cansasXML.ipf</nowiki> |
---|
75 | |
---|
76 | In the future, to retrieve an updated version of this support, go into |
---|
77 | the <nowiki>cansas-1dwg</nowiki> directory (created above) and type the command |
---|
78 | <pre>svn update</pre> |
---|
79 | This will check the repository and update files as needed. |
---|
80 | |
---|
81 | == Installation == |
---|
82 | |
---|
83 | # License and Install IgorPro (should have already been done by now) |
---|
84 | # Quit IgorPro if it is running |
---|
85 | # Download XMLutils XOP. Either checkout from subversion (see above) or, with a web browser, go to http://svn.igorexchange.com/viewvc/packages/XMLutils/trunk/ |
---|
86 | # Install XMLutils XOP by double-clicking the installer for you operating system. |
---|
87 | # 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 |
---|
88 | # Copy cansasXML.ipf file to <nowiki>...\Wavemetrics\Igor Pro Folder\User Procedures</nowiki> (or file system equivalent) |
---|
89 | # Then, you should be able to restart IgorPro and progress from there |
---|
90 | |
---|
91 | == Usage Notes == |
---|
92 | |
---|
93 | To use the canSASxml.ipf procedure, you must have the XMLutils XOP |
---|
94 | IGOR plugin installed. This may be downloaded from the IgorExchange |
---|
95 | Project site. There are installer executables contained in the |
---|
96 | download that will do all the installation for you. Each installer will place |
---|
97 | the XOP in the folder |
---|
98 | <nowiki>...\Wavemetrics\Igor Pro Folder\User Procedures\motofit\XMLutils</nowiki>, |
---|
99 | and create |
---|
100 | a shortcut/alias to the plugin in |
---|
101 | <nowiki>...\Wavemetrics\Igor Pro Folder\Igor Extensions</nowiki>. |
---|
102 | |
---|
103 | |
---|
104 | == List of Functions == |
---|
105 | |
---|
106 | These are (most of) the FUNCTIONS in the cansasXML.ipf code. |
---|
107 | The only functions of interest are '''CS_XmlReader(fileName)''' |
---|
108 | which reads the named XML file and and loads SAS data and the two demonstration |
---|
109 | functions '''prj_grabMyXmlData()''' and '''prjTest_cansas1d()''' |
---|
110 | that together show a usage example. |
---|
111 | |
---|
112 | ;'''CS_XmlReader(fileName)''': open a canSAS 1-D reduced SAS XML data file |
---|
113 | *input: ''fileName'' (string) name of canSAS XML file (can include file system path name to file) |
---|
114 | *returns: |
---|
115 | **0 successful |
---|
116 | **-1: XML file not found |
---|
117 | **-2: root element is not <SASroot> |
---|
118 | **-3: <SASroot> version is not 1.0 |
---|
119 | **-4: no <SASentry> elements |
---|
120 | ;CS_1i_parseXml(fileID): given a file ID returned from '''XMLOpenFile()''', parses that file for SAS data and metadata |
---|
121 | ;CS_1i_collectMetadata(fileID, sasEntryPath): gathers metadata from the named SASentry (XPathStr) |
---|
122 | ;CS_appendMetaData(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> |
---|
123 | ;CS_findElementIndex(matchStr): looks for element index in structure ''W_ElementList'' returned from call to '''XmlElemList(fileID)''' |
---|
124 | ;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. |
---|
125 | ;CS_XPath_NS(simpleStr): this function adds namespace info as necessary to simpleStr (an XPath) |
---|
126 | ;CS_buildXpathStr(prefix, value): this function can be used only with very simple XPath constructions |
---|
127 | ;CS_XmlStrFmXpath(fileID, prefix, value): Calls '''XmlStrFmXpath()''' with proper namespace prefix attached. Trims the result string. |
---|
128 | ;CS_simpleXmlWaveFmXpath(fileID, prefix, value): Calls '''XMLwaveFmXpath()''' with proper namespace prefix attached. |
---|
129 | ;CS_simpleXmlListXpath(fileID, prefix, value): Calls '''XMLlistXpath()''' with proper namespace prefix attached. |
---|
130 | ;TrimWS(str): Calls '''TrimWSL(TrimWSR(str))''' |
---|
131 | ;TrimWSL(str): Trims white space from left (leading) end of '''str''' |
---|
132 | ;TrimWSR(str): Trims white space from right (trailing) end of '''str''' |
---|
133 | ;CS_updateWaveNote(wavName, key, value): adds (or replaces) definition of ''key''=''value'' in the wave note of ''wavName'' |
---|
134 | ;CS_1i_extractIdataColumn2Wave(fileID, basePath, colName, wavName): This function pulls one column of data from each <nowiki><Idata></nowiki> element. It is easier to write this as a single function than debug it all the times it is needed. <br /> Avoid the use of the semicolon in anything that might make it into the IgorPro wavenote since the semicolon is a list delimiter. The import macro defends against this by converting all semicolons into the string " :semicolon: " |
---|
135 | ;CS_1i_extractSasData(fileID, SASdataPath, SASdata_folder): (1i in the function name signifies this is a function that supports INPUT from version 1.0 XML files) |
---|
136 | ;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>.) |
---|
137 | ;prjTest_cansas1d(): Demonstration function that calls '''CS_XmlReader(fileName)''' for many of the test data sets. |
---|