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

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

fixes #1
provides documentation for IgorPro? binding

File size: 8.0 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-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
41Subversion (http://subversion.tigris.org/) is a program for
42managing software versions.  There are command line and GUI clients
43for a variety of operating systems.  We won't recommend any here
44but will show the command lines necessary.
45
46==== XMLutils XOP ====
47
48The XMLutils XOP, written by Andrew Nelson (ANSTO), is hosted
49on the IgorExchange (http://www.igorexchange.com/).
50
51One good location to place the checked out XMLutils directory
52is in the Wavemetrics directory, next to the <nowiki>Igor Pro Folder</nowiki>
53<pre>svn://svn.igorexchange.com/packages/XMLutils/ XMLutils</pre>
54
55In the future, to retrieve an updated version of this support, go into
56the <nowiki>XMLutils</nowiki> directory (created above) and type the command
57<pre>svn update</pre>
58This will check the repository and update files as needed.
59If the installer program was updated, you;ll need to run the new
60installer program.  It is not necessary to uninstall first.
61
62The installer executables contained in the download will
63do 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
65plugin in /Igor Extensions.
66Packages from other facilities should place the XOP there as well.
67
68==== cansasXML.ipf ====
69
70Check 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
73This will download lots of extra files.  The file of interest is in the <nowiki>IgorPro</nowiki>
74directory and is called <nowiki>cansasXML.ipf</nowiki>
75
76In the future, to retrieve an updated version of this support, go into
77the <nowiki>cansas-1dwg</nowiki> directory (created above) and type the command
78<pre>svn update</pre>
79This 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
93To use the canSASxml.ipf procedure, you must have the XMLutils XOP
94IGOR plugin installed. This may be downloaded from the IgorExchange
95Project site. There are installer executables contained in the
96download that will do all the installation for you. Each installer will place
97the XOP in the folder
98<nowiki>...\Wavemetrics\Igor Pro Folder\User Procedures\motofit\XMLutils</nowiki>,
99and create
100a shortcut/alias to the plugin in
101<nowiki>...\Wavemetrics\Igor Pro Folder\Igor Extensions</nowiki>.
102
103
104==  List of Functions  ==
105
106These are (most of) the FUNCTIONS in the cansasXML.ipf code.
107The only functions of interest are '''CS_XmlReader(fileName)'''
108which reads the named XML file and and loads SAS data and the two demonstration
109functions '''prj_grabMyXmlData()''' and '''prjTest_cansas1d()'''
110that 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.
Note: See TracBrowser for help on using the repository browser.