Changeset 250


Ignore:
Timestamp:
Aug 29, 2012 1:47:16 AM (7 years ago)
Author:
prjemian
Message:

refs #24

Location:
1dwg/trunk/doc/source
Files:
7 edited

Legend:

Unmodified
Added
Removed
  • 1dwg/trunk/doc/source/binding-fortran.rst

    r244 r250  
    11.. $Id$ 
     2 
     3.. index:: ! binding; FORTRAN 
    24 
    35.. _fortran.binding: 
     
    68FORTRAN 
    79================ 
     10 
     11The development of the FORTRAN language,  
     12so beloved of scientists, pre-dates the development of XML.  
     13And it shows. FORTRAN is not a language that manipulates strings with ease,  
     14and this makes parsing XML decidedly awkward.  
     15So unless you *really* must use FORTRAN,  
     16you are probably better off with C/C++ (or something else more 'modern'),  
     17see for example Daniel Veillard's LIBXML2 library at http://xmlsoft.org/  
     18or Frank van den Berghen's parser at  
     19http://www.applied-mathematics.net/tools/xmlParser.html. 
     20 
     21If you have to use a dialect earlier than FORTRAN-90 (F90),  
     22then the chances are you will have to code your own parser. 
     23 
     24Software Development Kits 
     25============================== 
     26 
     27For later dialects, there are some SDKs available on the Web: 
     28 
     29**F90** 
     30         
     31        * *XMLPARSE* - by Arjen Markus at http://xml-fortran.sourceforge.net/ 
     32        * *FoX* - by Toby White  others at http://uszla.me.uk/space/software/FoX/ 
     33 
     34**F95** 
     35 
     36        * *XML* - by Mart Rentmeester at http://nn-online.org/code/xml/ 
     37 
     38 
     39canSAS 1-D SAS XML v1.0 support 
     40====================================== 
     41 
     42.. sidebar:: Needs update to v1.1 
     43 
     44        This update is expected to follow soon on the release of v1.1 
     45 
     46Steve King[mailto:s.m.king@rl.ac.uk] (ISIS) has provided a F77 routine  
     47(http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/fortran/SASXML_G77.F)  
     48that will read cansas1d/1.0 XML files. 
  • 1dwg/trunk/doc/source/binding-igorpro.rst

    r244 r250  
    11.. $Id$ 
    22 
     3.. index:: ! binding; IgorPro 
    34 
    45.. _igorpro.binding: 
     
    78IgorPro 
    89================ 
     10 
     11An import tool (binding) for IgorPro has been created (*cansasXML.ipf*). You can check out 
     12the IgorPro working directory from the SVN server (see instructions below). 
     13 
     14To use the *canSASxml.ipf* procedure,  
     15you must have the XMLutils XOP IGOR plugin installed. 
     16See the :ref:`IgorPro Binding Usage Notes` section below. 
     17 
     18.. note:: 
     19        Note that this tool is not a true binding [#]_ 
     20        in that the structure of the  
     21        XML file is not replicated in IgorPro data structures.  
     22        This tool reads the vectors of 1-D SAS data (*Q*, *I*, ...)  
     23        into IgorPro waves (*Qsas*, *Isas*, ...). The tool also reads  
     24        most of the metadata into an IgorPro textWave for use by other  
     25        support in IgorPro. 
     26         
     27        .. [#] For example, see *data binding* from  
     28                http://en.wikipedia.org/wiki/Binding_%28computer_science%29 
     29 
     30.. note:: 
     31        Note that the code described here is *not a complete user interface*. 
     32        (See further comments below.) It is expected that this code will be called by a graphical 
     33        user interface routine and that routine will handle the work of copying the loaded SAS data 
     34        in IgorPro from the *root:Packages:CS_XMLreader* data folder to the destination of choice 
     35        (including any renaming of waves as desired).  
     36 
     37 
     38**file** 
     39        http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/IgorPro/cansasXML.ipf 
     40 
     41**author** 
     42        Pete R. Jemian <jemian@anl.gov> 
     43 
     44**date** 
     45        2009-09-02 
     46 
     47**version** 
     48        1.11 (**requires** latest XMLutils XOP -- see below) 
     49 
     50**purpose** 
     51        Implement an IgorPro file reader to read the canSAS 1-D reduced SAS 
     52        data in XML files that adhere to the cansas1d/1.1 standard. 
     53 
     54**URL** 
     55        *TRAC* 
     56                http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/IgorPro/cansasXML.ipf 
     57        *SVN* 
     58                http://svn.smallangles.net/svn/canSAS/1dwg/trunk/IgorPro/cansasXML.ipf 
     59 
     60.. index:: ! IgorPro package; XMLutils XOP 
     61 
     62**requires** 
     63        * IgorPro: http://www.wavemetrics.com  
     64        * *XMLutils* XOP: http://www.igorexchange.com/project/XMLutils 
     65        * minimum requirement: IGOR.5.04.x-1.x-dev (circa 2008-Aug-22) 
     66                         
     67 
     68Checkout of support code in Subversion 
     69======================================= 
     70 
     71Subversion (http://subversion.tigris.org/) is a program for  
     72managing software 
     73versions. There are command line and GUI clients for a  
     74variety of operating systems. We 
     75won't recommend any here but will show the command lines necessary. 
     76 
     77.. index::  
     78        single: XMLutils XOP 
     79        single: IgorExchange 
     80 
     81.. _XMLutils XOP: 
     82 
     83*XMLutils* XOP 
     84------------------ 
     85 
     86The *XMLutils* XOP, written by Andrew Nelson (ANSTO),  
     87is hosted on the IgorExchange (http://www.igorexchange.com/). 
     88 
     89One good location to place the checked out *XMLutils* directory is in the 
     90*Wavemetrics* directory, next to the *Igor Pro Folder*. 
     91 
     92Here is the subversion checkout command: 
     93 
     94        .. code-block:: guess 
     95         
     96                svn co svn://svn.igorexchange.com/packages/XMLutils/ XMLutils 
     97 
     98To retrieve an updated version of this support in the future, go into the 
     99*XMLutils* directory (created above) and type either of these commands: 
     100 
     101        .. code-block:: text 
     102         
     103                svn update 
     104                svn up 
     105 
     106This will check the repository and update local files as needed. 
     107If the installer program was updated, you'll need to run the 
     108new installer program. It is not necessary to uninstall first. 
     109 
     110The installer executables contained in the download will do all the installation 
     111for you. They will place the XOP in the folder */User Procedures/motofit/XMLutils*,  
     112and create a shortcut/alias to the plugin in *./Igor Extensions*.  
     113Packages from other facilities should place the XOP there as well.  
     114 
     115 
     116.. index:: ! cansasXML.ipf 
     117 
     118*cansasXML.ipf* 
     119-------------------- 
     120 
     121Check out the canSAS 1d SAS XML reader from the subversion repository: 
     122 
     123        .. code-block:: text 
     124         
     125                svn checkout http://svn.smallangles.net/svn/canSAS/1dwg/trunk cansas-1dwg 
     126 
     127This will download lots of extra files. The file of interest is in the 
     128IgorPro directory and is called *cansasXML.ipf* 
     129 
     130To retrieve an updated version of this support in the future, 
     131go into the *cansas-1dwg* directory (created above) and type the command:: 
     132 
     133        svn update 
     134 
     135This will check the repository and update files as needed. 
     136 
     137 
     138Installation 
     139================= 
     140 
     141#. License and Install the *IgorPro* application  
     142        (should have already done this step by now) 
     143#. Quit *IgorPro* if it is running 
     144#. Download *XMLutils* XOP. Either checkout from subversion (see above) or, with a 
     145        web browser, visit http://svn.igorexchange.com/viewvc/packages/XMLutils/trunk/ 
     146#. Install *XMLutils* XOP by double-clicking the installer for your operating system. 
     147#. Download *cansasXML.ipf*. Either checkout from subversion (see above) or, with 
     148        a web browser, copy *cansasXML.ipf* from the on-line subversion repository. 
     149        (http://svn.smallangles.net/svn/canSAS/1dwg/trunk/IgorPro/cansasXML.ipf) 
     150#. Copy *cansasXML.ipf* file to *...WavemetricsIgor Pro FolderUser Procedures* 
     151        (or file system equivalent) 
     152#. Then, you should be able to restart *IgorPro* and progress from there. 
     153 
     154 
     155.. _IgorPro Binding Usage Notes: 
     156 
     157Usage Notes 
     158=============== 
     159 
     160To use the *canSASxml.ipf* procedure, you must have the *XMLutils* XOP IgorPro plugin 
     161installed. This may be downloaded from the IgorExchange Project site. There are 
     162installer executables contained in the download that will do all the installation for 
     163you. Each installer will place the XOP in the folder  
     164*...Wavemetrics:Igor Pro Folder:User Procedures:motofit:XMLutils*,  
     165and create a shortcut/alias to the plugin in 
     166*...Wavemetrics:Igor Pro Folder:Igor Extensions*. 
     167 
     168 
     169 
     170.. index:: IgorPro; *CS_XmlReader()* 
     171 
     172What it does 
     173============ 
     174 
     175Given an XML file, **CS_XmlReader(fileName)** attempts 
     176to open the file and read its contents as if it conformed to the canSAS XML standard 
     177for reduced 1-D SAS data (cansas1d/1.1, also known as SASXML). If the file is found to be 
     178non-conforming, then *CS_XmlReader(fileName)* returns 
     179with an error code (show below), otherwise it returns *0*, indicating *no error*. 
     180All data read by this code is left in the 
     181IgorPro data folder *root:Packages:CS_XMLreader* for pickup by the calling routine. 
     182(Two examples are provided to show how a routine might retrieve the data.) 
     183  
     184.. index:: I(Q) 
     185 
     186After opening the XML file (with a file identifier *fileID*), 
     187control is passed to *CS_1i_parseXml(fileID)* which then 
     188walks through the XML elements. For each *SASentry* in the 
     189file, a new data folder is created with the name derived from the *Title* element (or best 
     190effort determination).  Efforts are taken to avoid duplication of data folder names (using 
     191standard IgorPro routines). For *SASentry* elements that 
     192contain more than one *SASdata* element, a *SASdata* folder 
     193is created for each.  The corresponding  :math:`I(Q)` is placed in that  
     194subfolder.  When only one *SASdata* is found, the 
     195:math:`I(Q)` data is placed in the main *Title* folder. 
     196 
     197**data columns** 
     198        Each column of data in the *SASdata/Idata/** table 
     199        is placed into a single IgorPro wave. At present, the code does not check for 
     200        non-standard data columns.(The capability is built into the code but is deactivated 
     201        at present). 
     202 
     203**metadata** 
     204        Additional :index:`metadata` is collected into a single text wave 
     205        (*metadata*) where the first column is an identifier (or 
     206        *key*) and the second identifier is the *value*. Only those keys with non-empty values  
     207        are retained in the metadata table. 
     208         
     209        .. caution:: The *values* are not checked for  
     210            characters that may cause trouble when placed in a wave note. This will be the  
     211            responsibility of the calling routine to *clean these up* if the need arises. 
     212         
     213        The code checks for most metadata elements and will check for  
     214        repeated elements where the standard permits. 
     215         
     216        Here is an example of the metadata for the :ref:`case_study-collagen`. 
     217         
     218        .. rubric:: metadata for the *cs_collagen_full.xml* case study 
     219         
     220        =======   ===============================================   ===================================================================== 
     221        row `i`   key: `metadata[i][0]`                             value: `metadata[i][1]` 
     222        =======   ===============================================   ===================================================================== 
     223        0         xmlFile                                           *cs_collagen_full.xml* 
     224        1         namespace                                         ``cansas1d/1.1`` 
     225        2         *Title*                                           ``dry chick collagen, d = 673 A, 6531 eV, X6B`` 
     226        3         *Run*                                             ``Sep 19 1994 01:41:02 am`` 
     227        4         *SASsample/ID*                                    ``dry chick collagen, d = 673 A, 6531 eV, X6B`` 
     228        5         *SASinstrument/name*                              ``X6B, NSLS, BNL`` 
     229        6         *SASinstrument/SASsource/radiation*               ``X-ray synchrotron`` 
     230        7         *SASinstrument/SASsource/wavelength*              ``1.898`` 
     231        8         *SASinstrument/SASsource/wavelength/@unit*        ``A`` 
     232        9         *SASinstrument/SASdetector/@name*                 ``X6B PSD`` 
     233        10        *SASnote*                                         :: 
     234                                                                     
     235                                                                            Sep 19 1994     01:41:02 am     Elt: 00090 Seconds  
     236                                                                            ID: No spectrum identifier defined 
     237                                                                            Memory Size: 8192 Chls  Conversion Gain: 1024  Adc Offset: 0000 Chls 
     238                                                                             
     239                                                                            dry chick collagen, d = 673 A 
     240                                                                            6531 eV, X6B 
     241        =======   ===============================================   ===================================================================== 
     242 
     243 
     244.. index:: XML; foreign elements 
     245 
     246**XML foreign namespace elements** 
     247        These are ignored at this time. 
     248 
     249**XML namespace and header** 
     250        The routine does a *best-efforts* check to ensure that the 
     251        given XML file conforms to the required :ref:`XML file header <XML.header>`. 
     252        If you take a minimalist view (*a.k.a.* a shortcut), it is likely that your file may be 
     253        refused by this and other readers. Pay particular attention to UPPER and lower case in 
     254        the text **cansas1d/1.1** as this is a **key component** used to index through the XML file. 
     255 
     256**XML stylesheet processing-instruction is not generated** 
     257        The :ref:`XMLutils XOP` package does not provide a method to insert the prescribed  
     258        :index:`XML stylesheet` processing-instruction into the XML data file. 
     259         
     260                .. code-block:: xml 
     261                 
     262                        <?xml-stylesheet type=text/xsl href=example.xsl ?> 
     263 
     264        If this processing-instruction is desired, it must be added to each XML data file by 
     265        other methods such as use of a text editor or application of an XSLT transformation. 
     266 
     267 
     268List of Functions 
     269==================== 
     270 
     271.. index::  
     272        single: IgorPro; *CS_XmlReader()* 
     273        single: IgorPro; *prj_grabMyXmlData()* 
     274        single: IgorPro; *prjTest_cansas1d()* 
     275 
     276These are (most of) the FUNCTIONS in the *cansasXML.ipf* code.   
     277The only functions of interest are: 
     278 
     279        *CS_XmlReader(fileName)* 
     280                reads the named XML file and and loads SAS data 
     281        *prj_grabMyXmlData()* 
     282                demonstration function to show a usage example 
     283        *prjTest_cansas1d()* 
     284                demonstration function to show a usage example 
     285 
     286 
     287 
     288 
     289 
     290 
     291.. 
     292            <section> 
     293                <title></title> 
     294                <itemizedlist mark="opencircle"> 
     295                    <listitem> 
     296                        <para> 
     297                            <emphasis role="bold">CS_XmlReader(fileName)*:  
     298                            <indexterm> 
     299                                <primary>binding</primary> 
     300                                <secondary>IgorPro</secondary> 
     301                                <tertiary>*CS_XmlReader()*</tertiary> 
     302                            </indexterm> 
     303                            open a canSAS 1-D 
     304                            reduced SAS XML data file </para> 
     305                    </listitem> 
     306                </itemizedlist> 
     307                <itemizedlist mark="opencircle"> 
     308                    <listitem> 
     309                        <para> input: *fileName* (string) name of canSAS XML file (can 
     310                            include file system path name to file) </para> 
     311                    </listitem> 
     312                    <listitem> 
     313                        <para> returns: </para> 
     314                        <itemizedlist mark="opencircle"> 
     315                            <listitem> 
     316                                <para> 0 successful </para> 
     317                            </listitem> 
     318                            <listitem> 
     319                                <para> -1: XML file not found </para> 
     320                            </listitem> 
     321                            <listitem> 
     322                                <para> -2: root element is not SASroot with valid canSAS namespace </para> 
     323                            </listitem> 
     324                            <listitem> 
     325                                <para> -3: SASroot version is not 1.0 </para> 
     326                            </listitem> 
     327                            <listitem> 
     328                                <para> -4: no SASentry elements (NOT USED NOW) </para> 
     329                            </listitem> 
     330                            <listitem> 
     331                                <para> -5: XOPutils needs upgrade </para> 
     332                            </listitem> 
     333                        </itemizedlist> 
     334                    </listitem> 
     335                </itemizedlist> 
     336                <itemizedlist mark="opencircle"> 
     337                    <listitem> 
     338                        <para> CS_1i_parseXml(fileID): 
     339                            <indexterm> 
     340                                <primary>binding</primary> 
     341                                <secondary>IgorPro</secondary> 
     342                                <tertiary>*CS_1i_parseXml()*</tertiary> 
     343                            </indexterm> 
     344                            <emphasis role="bold">This is what guides the 
     345                                work*, given a file ID returned from <emphasis role="bold" 
     346                                    >XMLOpenFile()*, parses that file for SAS data and metadata 
     347                            <indexterm><primary>metadata</primary></indexterm> 
     348                            (1i in the function name signifies this is a function that supports  
     349                            INPUT from version 1.0 XML files) </para> 
     350                    </listitem> 
     351                    <listitem> 
     352                        <para> CS_1i_getOneSASdata(fileID, Title, SASdataPath) :  
     353                            <indexterm> 
     354                                <primary>binding</primary> 
     355                                <secondary>IgorPro</secondary> 
     356                                <tertiary>*CS_1i_getOneSASdata()*</tertiary> 
     357                            </indexterm> 
     358                            harvest the data and metadata 
     359                            <indexterm><primary>metadata</primary></indexterm> 
     360                            in the specific SASdata element </para> 
     361                    </listitem> 
     362                    <listitem> 
     363                        <para> CS_1i_getOneVector(file,prefix,XML_name,Igor_name) :  
     364                            <indexterm> 
     365                                <primary>binding</primary> 
     366                                <secondary>IgorPro</secondary> 
     367                                <tertiary>*CS_1i_getOneVector()*</tertiary> 
     368                            </indexterm> 
     369                            harvest just one column 
     370                            (vector) of data </para> 
     371                    </listitem> 
     372                    <listitem> 
     373                        <para> CS_1i_GetReducedSASdata(fileID, SASdataPath) :  
     374                            <indexterm> 
     375                                <primary>binding</primary> 
     376                                <secondary>IgorPro</secondary> 
     377                                <tertiary>*CS_1i_GetReducedSASdata()*</tertiary> 
     378                            </indexterm> 
     379                            grab the data and put it in 
     380                            the working data folder </para> 
     381                    </listitem> 
     382                    <listitem> 
     383                        <para> CS_1i_locateTitle(fileID, SASentryPath) :  
     384                            <indexterm> 
     385                                <primary>binding</primary> 
     386                                <secondary>IgorPro</secondary> 
     387                                <tertiary>*CS_1i_locateTitle()*</tertiary> 
     388                            </indexterm> 
     389                            determine the title for this 
     390                            experiment </para> 
     391                    </listitem> 
     392                    <listitem> 
     393                        <para> CS_appendMetaData(fileID, key, xpath, value) :  
     394                            <indexterm> 
     395                                <primary>binding</primary> 
     396                                <secondary>IgorPro</secondary> 
     397                                <tertiary>*CS_appendMetaData()*</tertiary> 
     398                            </indexterm> 
     399                            queries XML file for <emphasis 
     400                                role="bold">xpath*. If <emphasis role="bold">value* is 
     401                            not empty, appends it to <emphasis role="bold">metadata* 
     402                            <indexterm><primary>metadata</primary></indexterm> 
     403                            where *last* is the new last row: metadata[last][0]=key; 
     404                            metadata[last][1]=value </para> 
     405                    </listitem> 
     406                    <listitem> 
     407                        <para> CS_buildXpathStr(prefix, value) :  
     408                            <indexterm> 
     409                                <primary>binding</primary> 
     410                                <secondary>IgorPro</secondary> 
     411                                <tertiary>*CS_buildXpathStr()*</tertiary> 
     412                            </indexterm> 
     413                            this function can be used only with very 
     414                            simple XPath constructions </para> 
     415                    </listitem> 
     416                    <listitem> 
     417                        <para> CS_cleanFolderName(proposal) :  
     418                            <indexterm> 
     419                                <primary>binding</primary> 
     420                                <secondary>IgorPro</secondary> 
     421                                <tertiary>*CS_cleanFolderName()*</tertiary> 
     422                            </indexterm> 
     423                            given a proposal string, returns a candidate 
     424                            folder name for immediate use </para> 
     425                    </listitem> 
     426                    <listitem> 
     427                        <para> CS_findElementIndex(matchStr) :  
     428                            <indexterm> 
     429                                <primary>binding</primary> 
     430                                <secondary>IgorPro</secondary> 
     431                                <tertiary>*CS_findElementIndex()*</tertiary> 
     432                            </indexterm> 
     433                            looks for element index in structure 
     434                                *W_ElementList* returned from call to <emphasis 
     435                                role="bold">XmlElemList(fileID)* 
     436                        </para> 
     437                    </listitem> 
     438                    <listitem> 
     439                        <para> CS_getDefaultNamespace(fileID) :  
     440                            <indexterm> 
     441                                <primary>binding</primary> 
     442                                <secondary>IgorPro</secondary> 
     443                                <tertiary>*CS_getDefaultNamespace()*</tertiary> 
     444                            </indexterm> 
     445                            returns the string containing the default 
     446                            namespace for the XML file </para> 
     447                    </listitem> 
     448                    <listitem> 
     449                        <para> CS_registerNameSpaces() :  
     450                            <indexterm> 
     451                                <primary>binding</primary> 
     452                                <secondary>IgorPro</secondary> 
     453                                <tertiary>*CS_registerNameSpaces()*</tertiary> 
     454                            </indexterm> 
     455                            Builds a table of all namespaces used in the XML 
     456                            file and appends <emphasis role="bold">W_ElementList* with full 
     457                            namespace-xpath string for each element. </para> 
     458                    </listitem> 
     459                    <listitem> 
     460                        <para> CS_simpleXmlListXpath(fileID, prefix, value) :  
     461                            <indexterm> 
     462                                <primary>binding</primary> 
     463                                <secondary>IgorPro</secondary> 
     464                                <tertiary>*CS_simpleXmlListXpath()*</tertiary> 
     465                            </indexterm> 
     466                            Calls <emphasis role="bold" 
     467                                >XMLlistXpath()* with proper namespace prefix attached. </para> 
     468                    </listitem> 
     469                    <listitem> 
     470                        <para> CS_simpleXmlWaveFmXpath(fileID, prefix, value) :  
     471                            <indexterm> 
     472                                <primary>binding</primary> 
     473                                <secondary>IgorPro</secondary> 
     474                                <tertiary>*CS_simpleXmlWaveFmXpath()*</tertiary> 
     475                            </indexterm> 
     476                            Calls <emphasis role="bold" 
     477                                >XMLwaveFmXpath()* with proper namespace prefix attached. </para> 
     478                    </listitem> 
     479                    <listitem> 
     480                        <para> CS_updateWaveNote(wavName, key, value) :  
     481                            <indexterm> 
     482                                <primary>binding</primary> 
     483                                <secondary>IgorPro</secondary> 
     484                                <tertiary>*CS_updateWaveNote()*</tertiary> 
     485                            </indexterm> 
     486                            adds (or replaces) definition of 
     487                                *key*=*value* in the wave note of 
     488                                *wavName* 
     489                        </para> 
     490                    </listitem> 
     491                    <listitem> 
     492                        <para> CS_XmlStrFmXpath(fileID, prefix, value) :  
     493                            <indexterm> 
     494                                <primary>binding</primary> 
     495                                <secondary>IgorPro</secondary> 
     496                                <tertiary>*CS_XmlStrFmXpath()*</tertiary> 
     497                            </indexterm> 
     498                            Calls <emphasis role="bold" 
     499                                >XmlStrFmXpath()* with proper namespace prefix attached. Trims the 
     500                            result string. </para> 
     501                    </listitem> 
     502                    <listitem> 
     503                        <para> CS_XPath_NS(simpleStr) :  
     504                            <indexterm> 
     505                                <primary>binding</primary> 
     506                                <secondary>IgorPro</secondary> 
     507                                <tertiary>*CS_XPath_NS()*</tertiary> 
     508                            </indexterm> 
     509                            this function adds namespace info as necessary to 
     510                            simpleStr (an XPath) </para> 
     511                    </listitem> 
     512                    <listitem> 
     513                        <para> TrimWS(str) :  
     514                            <indexterm> 
     515                                <primary>binding</primary> 
     516                                <secondary>IgorPro</secondary> 
     517                                <tertiary>*TrimWS()*</tertiary> 
     518                            </indexterm> 
     519                            Calls <emphasis role="bold">TrimWSL(TrimWSR(str))* 
     520                        </para> 
     521                    </listitem> 
     522                    <listitem> 
     523                        <para> TrimWSL(str) :  
     524                            <indexterm> 
     525                                <primary>binding</primary> 
     526                                <secondary>IgorPro</secondary> 
     527                                <tertiary>*TrimWSL()*</tertiary> 
     528                            </indexterm> 
     529                            Trims white space from left (leading) end of <emphasis 
     530                                role="bold">str* 
     531                        </para> 
     532                    </listitem> 
     533                    <listitem> 
     534                        <para> TrimWSR(str) :  
     535                            <indexterm> 
     536                                <primary>binding</primary> 
     537                                <secondary>IgorPro</secondary> 
     538                                <tertiary>*TrimWSR()*</tertiary> 
     539                            </indexterm> 
     540                            Trims white space from right (trailing) end of <emphasis 
     541                                role="bold">str* 
     542                        </para> 
     543                    </listitem> 
     544                    <listitem> 
     545                        <para> prjTest_cansas1d() :  
     546                            <indexterm> 
     547                                <primary>binding</primary> 
     548                                <secondary>IgorPro</secondary> 
     549                                <tertiary>*prjTest_cansas1d()*</tertiary> 
     550                            </indexterm> 
     551                            Demonstration function that calls <emphasis role="bold" 
     552                                >CS_XmlReader(fileName)* for many of the test data sets. </para> 
     553                    </listitem> 
     554                    <listitem> 
     555                        <para> prj_grabMyXmlData() :  
     556                            <indexterm> 
     557                                <primary>binding</primary> 
     558                                <secondary>IgorPro</secondary> 
     559                                <tertiary>*prj_grabMyXmlData()*</tertiary> 
     560                            </indexterm> 
     561                            Demonstration function that moves loaded data from 
     562                            root:Packages:CS_XMLreader to a user's data folder. (In this 
     563                                *example*, that folder is root:PRJ_canSAS.) </para> 
     564                    </listitem> 
     565                    <listitem> 
     566                        <para> testCollette() :  
     567                            <indexterm> 
     568                                <primary>binding</primary> 
     569                                <secondary>IgorPro</secondary> 
     570                                <tertiary>*testCollette()*</tertiary> 
     571                            </indexterm> 
     572                            Demonstration function that reads an ISIS/LOQ file and 
     573                            copies the data to the root folder a la COLLETE </para> 
     574                    </listitem> 
     575                </itemizedlist> 
     576            </section> 
     577 
     578 
     579 
     580 
     581            <section> 
     582                <title>Example test case</title> 
     583                <para> Here is an example running the test routine *prjTest_cansas1d()*. 
     584                    <programlisting linenumbering="numbered"> 
     585        *prjTest_cansas1d() 
     586        XMLopenfile: File(path) to open doesn't exist, or file can't be opened 
     587        elmo.xml either not found or cannot be opened for reading 
     588            Completed in 0.00669666 seconds 
     589        XMLopenfile: XML file was not parseable 
     590        cansasXML.ipf: failed to parse XML 
     591            Completed in 0.0133704 seconds 
     592        root element is not SASroot with valid canSAS namespace 
     593            Completed in 0.0134224 seconds 
     594        bimodal-test1.xml                identified as: cansas1d/1.1 XML file 
     595            Title: SAS bimodal test1  
     596            Completed in 0.068654 seconds 
     597        root element is not SASroot with valid canSAS namespace 
     598            Completed in 0.0172572 seconds 
     599        root element is not SASroot with valid canSAS namespace 
     600            Completed in 0.0123102 seconds 
     601        root element is not SASroot with valid canSAS namespace 
     602            Completed in 0.00930118 seconds 
     603        ISIS_SANS_Example.xml            identified as: cansas1d/1.1 XML file 
     604            Title: standard can 12mm SANS  
     605            Completed in 0.0410387 seconds 
     606        W1W2.xml                 identified as: cansas1d/1.1 XML file 
     607            Title: standard can 12mm SANS  
     608            Title: TK49 standard 12mm SANS  
     609            Completed in 0.0669074 seconds 
     610        ill_sasxml_example.xml           identified as: cansas1d/1.1 XML file 
     611            Title: ILL-D22 example: 7D1 2mm  
     612            Completed in 0.0332752 seconds 
     613        isis_sasxml_example.xml                  identified as: cansas1d/1.1 XML file 
     614            Title: LOQ TK49 Standard 12mm C9  
     615            Completed in 0.0388868 seconds 
     616        r586.xml                 identified as: cansas1d/1.1 XML file 
     617            Title: ILL-D11 example1: 2A 5mM 0%D2O  
     618            Completed in 0.0213737 seconds 
     619        r597.xml                 identified as: cansas1d/1.1 XML file 
     620            Title: ILL-D11 example2: 2A 5mM 0%D2O  
     621            Completed in 0.0221894 seconds 
     622        xg009036_001.xml                 identified as: cansas1d/1.1 XML file 
     623            Title: det corrn 5m  
     624            Completed in 0.0286721 seconds 
     625        cs_collagen.xml                  identified as: cansas1d/1.1 XML file 
     626            Title: dry chick collagen, d = 673 A, 6531 eV, X6B  
     627            Completed in 0.0296247 seconds 
     628        cs_collagen_full.xml             identified as: cansas1d/1.1 XML file 
     629            Title: dry chick collagen, d = 673 A, 6531 eV, X6B  
     630            Completed in 0.0751836 seconds 
     631        cs_af1410.xml            identified as: cansas1d/1.1 XML file 
     632            Title: AF1410-10 (AF1410 steel aged 10 h)  
     633            Title: AF1410-8h (AF1410 steel aged 8 h)  
     634            Title: AF1410-qu (AF1410 steel aged 0.25 h)  
     635            Title: AF1410-cc (AF1410 steel aged 100 h)  
     636            Title: AF1410-2h (AF1410 steel aged 2 h)  
     637            Title: AF1410-50 (AF1410 steel aged 50 h)  
     638            Title: AF1410-20 (AF1410 steel aged 20 h)  
     639            Title: AF1410-5h (AF1410 steel aged 5 h)  
     640            Title: AF1410-1h (AF1410 steel aged 1 h)  
     641            Title: AF1410-hf (AF1410 steel aged 0.5 h)  
     642            Completed in 0.338425 seconds 
     643        XMLopenfile: File(path) to open doesn't exist, or file can't be opened 
     644        cansas1d-template.xml either not found or cannot be opened for reading 
     645            Completed in 0.00892823 seconds 
     646        1998spheres.xml                  identified as: cansas1d/1.1 XML file 
     647            Title: 255 nm PS spheres  
     648            Title: 460 nm PS spheres  
     649            Completed in 2.87649 seconds 
     650        XMLopenfile: File(path) to open doesn't exist, or file can't be opened 
     651        does-not-exist-file.xml either not found or cannot be opened for reading 
     652            Completed in 0.00404549 seconds 
     653        cs_rr_polymers.xml               identified as: cansas1d/1.1 XML file 
     654            Title: Round Robin Polymer A  
     655            Title: Round Robin Polymer B  
     656            Title: Round Robin Polymer C  
     657            Title: Round Robin Polymer D  
     658            Completed in 0.0943477 seconds 
     659        s81-polyurea.xml                 identified as: cansas1d/1.1 XML file 
     660            Title: S7 Neat Polyurea  
     661            Completed in 0.0361616 seconds 
     662            </programlisting> 
     663                </para> 
     664            </section> 
     665            <section> 
     666                <title>IgorPro Graphical User Interface</title> 
     667                <para> At least two groups are working on graphical user  
     668                    interfaces that use the canSAS 1-D 
     669                    SAS XML format binding to IgorPro. The GUIs are intended  
     670                    to be used with their suites of 
     671                    SAS analysis tools (and hide the details of using this  
     672                    support code from the user). </para> 
     673                <para> NOTE: There is no support yet for writing the data  
     674                    back into the canSAS format. 
     675                    Several details need to be described, and these are  
     676                    being collected on the discussion 
     677                    page for the XML format </para> 
     678                <section> 
     679                    <title>Irena tool suite</title> 
     680                    <para> Jan Ilavsky's  
     681                        <link  
     682                            xlink:href="http://usaxs.xor.aps.anl.gov/staff/ilavsky/irena.htm" 
     683                            ><emphasis role="bold">Irena*</link><footnote> 
     684                            <para> 
     685                                <link xlink:href="http://usaxs.xor.aps.anl.gov/staff/ilavsky/irena.htm" 
     686                                    ><literal 
     687                                        >http://usaxs.xor.aps.anl.gov/staff/ilavsky/irena.htm*</link> 
     688                            </para> 
     689                        </footnote> 
     690                        <indexterm significance="preferred"> 
     691                            <primary>IgorPro package</primary> 
     692                            <secondary>Irena tool suite</secondary> 
     693                        </indexterm> 
     694                        tool suite for IgorPro has a GUI to 
     695                        load the data found in the XML file.  
     696                        Refer to the WWW site for more details. </para> 
     697                </section> 
     698            </section> 
  • 1dwg/trunk/doc/source/binding-php.rst

    r244 r250  
    66PHP 
    77================ 
     8 
     9.. sidebar:: Not much is written here.   
     10 
     11        Needs work. 
     12 
     13A demonstration of writing the cansas1d/1.1 XML data format can be 
     14found in the *XmlWriter* form.  See the :ref:`XmlWriter` section for more details. 
  • 1dwg/trunk/doc/source/binding-python.rst

    r244 r250  
    11.. $Id$ 
     2 
     3.. index:: ! binding; Python 
    24 
    35.. _Python.binding: 
     
    79================ 
    810 
     11Specific support for the cansas1d/1.1 data standard in Python (http://danse.us/trac/sans) 
     12is being developed by NIST/NCNR (http://www.ncnr.nist.gov) 
     13as part of their contribution to the  
     14DANSE project (http://wiki.cacr.caltech.edu/danse). 
     15 
     16Here are some extremeley terse instructions (circa 2008) to get you started on a UNIX or Linux system: 
     17 
     18.. code-block:: guess 
     19        :linenos: 
     20         
     21        svn co http://danse.us/trac/sans/browser/trunk/DataLoader DataLoader 
     22        cd DataLoader 
     23        python setup.py install 
     24 
     25The release notes (http://danse.us/trac/sans/browser/trunk/DataLoader/release_notes.txt) 
     26have a list of the dependencies. 
     27 
     28 
     29.. rubric:: Comments 
     30 
     31Other constructive suggestions (that predate the NIST/NCNR support) have been gathered on this page. 
     32  
     33  
     34*gnosis.xml.objectify* 
     35========================= 
     36  
     37The *GnosisUtils* (http://freshmeat.net/projects/gnosisxml/) 
     38offer a method to read any XML file into Python data structures. This utility  
     39does not validate the XML against a specific XML Schema which can be both good  
     40(flexible, especially when XML Foreign Namespace elements are used) and not  
     41so good (XML content not guaranteed to be valid *by the rules*). 
     42 
     43A quick test of this turned up an acceptable result in that it was able to read  
     44several of the canSAS test XML files, including those with foreign namespaces.   
     45And **it was very easy**.  
     46(Especially with some help from http://www.xml.com/pub/a/2003/07/02/py-xml.html) 
     47 
     48Here is a quick example. 
     49 
     50Installation 
     51------------ 
     52 
     53Here is the condensed *GnosisUtils* installation (without all that output) steps.  
     54Your system may have *gnosis* already installed.  
     55You may also need sysAdmin privileges.  
     56You may need ... 
     57 
     58        .. code-block:: guess 
     59                :linenos: 
     60                 
     61                cd /tmp 
     62                wget http://freshmeat.net/redir/gnosisxml/22028/url_tgz/Gnosis_Utils-1.2.2.tar.gz 
     63                tar xzf Gnosis_Utils-1.2.2.tar.gz  
     64                cd Gnosis_Utils-1.2.2/ 
     65                python setup.py install_all 
     66 
     67.. index:: Python file; *python-test.py* 
     68 
     69Quick test in Python 
     70------------------------ 
     71 
     72.. sidebar:: Conclusion: OK 
     73 
     74        The *GnosisUtils* have the promise of being a useful tool to support  
     75        reading this format in Python.  Now, how to write back out... ? 
     76 
     77Here is the Python code (without all that output) (called *python-test.py*): 
     78 
     79        .. rubric:: *python-test.py* 
     80         
     81        .. code-block:: python 
     82                :linenos: 
     83                 
     84                import gnosis.xml.objectify 
     85                 
     86                sasxml = gnosis.xml.objectify.XML_Objectify('bimodal-test1.xml').make_instance()   
     87                print sasxml.SASentry.Title.PCDATA 
     88                print sasxml.SASentry.Run.PCDATA 
     89                print sasxml.SASentry.SASinstrument.name.PCDATA 
     90                data0 = sasxml.SASentry.SASdata.Idata[0] 
     91                print data0.Q.unit,  data0.I.unit 
     92                print data0.Q.PCDATA,  data0.I.PCDATA,  data0.Idev.PCDATA 
     93 
     94        .. rubric:: Output from *python-test.py* 
     95                 
     96        .. code-block:: guess 
     97                :linenos: 
     98                 
     99                [Pete@ubuntu,2441,cansas1dwg]$ ./python-test.py  
     100                SAS bimodal test1 
     101                1992 
     102                simulated SAS calculation 
     103                1/A 1/cm 
     104                0.0040157139 3497.473 90.72816 
     105 
     106        .. rubric:: Full session output 
     107                 
     108        .. code-block:: guess 
     109                :linenos: 
     110                 
     111                [Pete@ubuntu,2429,/tmp]$ cd /tmp 
     112                /tmp 
     113                [Pete@ubuntu,2430,/tmp]$ wget http://freshmeat.net/redir/gnosisxml/22028/url_tgz/Gnosis_Utils-1.2.2.tar.gz 
     114                --11:43:16--  http://freshmeat.net/redir/gnosisxml/22028/url_tgz/Gnosis_Utils-1.2.2.tar.gz 
     115                           => `Gnosis_Utils-1.2.2.tar.gz' 
     116                Resolving freshmeat.net... 66.35.250.168 
     117                Connecting to freshmeat.net|66.35.250.168|:80... connected. 
     118                HTTP request sent, awaiting response... 302 Found 
     119                Location: http://www.gnosis.cx/download/Gnosis_Utils.More/Gnosis_Utils-1.2.2.tar.gz [following] 
     120                --11:43:16--  http://www.gnosis.cx/download/Gnosis_Utils.More/Gnosis_Utils-1.2.2.tar.gz 
     121                           => `Gnosis_Utils-1.2.2.tar.gz' 
     122                Resolving www.gnosis.cx... 64.41.64.172 
     123                Connecting to www.gnosis.cx|64.41.64.172|:80... connected. 
     124                HTTP request sent, awaiting response... 200 OK 
     125                Length: 287,989 (281K) [application/x-tar] 
     126                 
     127                100%[==============================================================================>] 287,989       --.--K/s              
     128                 
     129                11:43:16 (2.47 MB/s) - `Gnosis_Utils-1.2.2.tar.gz' saved [287989/287989] 
     130                 
     131                [Pete@ubuntu,2431,/tmp]$ tar xzf Gnosis_Utils-1.2.2.tar.gz  
     132                [Pete@ubuntu,2432,/tmp]$ cd Gnosis_Utils-1.2.2/ 
     133                /tmp/Gnosis_Utils-1.2.2 
     134                [Pete@ubuntu,2433,Gnosis_Utils-1.2.2]$ python setup.py install_all 
     135                [Pete@ubuntu,2434,Gnosis_Utils-1.2.2]$ cd ~/workspace/cansas1dwg-regitte 
     136                [Pete@ubuntu,2435,cansas1dwg-regitte]$ python 
     137                Python 2.5.1 (r251:54863, May 18 2007, 16:56:43)  
     138                [GCC 3.4.4 (cygming special, gdc 0.12, using dmd 0.125)] on cygwin 
     139                Type "help", "copyright", "credits" or "license" for more information. 
     140                >>> import gnosis.xml.objectify 
     141                >>> sasxml = gnosis.xml.objectify.XML_Objectify('bimodal-test1.xml').make_instance()   
     142                >>> print sasxml.SASentry.Title.PCDATA 
     143                SAS bimodal test1 
     144                >>> print sasxml.SASentry.Run.PCDATA 
     145                1992 
     146                >>> print sasxml.SASentry.SASinstrument.name.PCDATA 
     147                simulated SAS calculation 
     148                >>> data0 = sasxml.SASentry.SASdata.Idata[0] 
     149                >>> print data0.Q.unit 
     150                1/A 
     151                >>> print data0.I.unit 
     152                1/cm 
     153                >>> print data0.Q.PCDATA,  data0.I.PCDATA,  data0.Idev.PCDATA 
     154                0.0040157139 3497.473 90.72816 
     155 
     156 
     157             
     158*generateDS.py* 
     159=============== 
     160 
     161.. sidebar:: Conclusion: not ready yet (2008-05-16) 
     162 
     163        Either the canSAS standard (by means of the cansas1d.xsd XML Schema)  
     164        is not ready or *generateDS.py* does not cover the  
     165        XML Schema requirements we have at this time. Either way,  
     166        this is not a viable tool to use now. 
     167 
     168*generateDS.py*  
     169(http://www.rexx.com/~dkuhlman/, http://www.rexx.com/~dkuhlman/generateDS.html)  
     170can build a binding (map the structure of the XML file directly into a  
     171Python data structure) for Python from an XML Schema. 
     172However, the cansas1d/1.1 XML schema (cansas1d.xsd) does not seem to  
     173fit the model.It seems, for now, that *generateDS-1.12a*  
     174fails on a certain *annotate* line. 
     175 
     176.. code-block:: guess 
     177        :linenos: 
     178         
     179        [Pete@ubuntu,2402,cansas1dwg]$ python  \ 
     180                        ~/generateDS-1.12a/generateDS.py  \ 
     181                        -p CS1D_  \ 
     182                        -o cansas1d.py  \ 
     183                        -s cansas1dsubs.py  \ 
     184                        cansas1d.xsd 
     185        Traceback (most recent call last): 
     186          File "/home/Pete/generateDS-1.12a/generateDS.py", line 3997, in &lt;module> 
     187            main() 
     188          File "/home/Pete/generateDS-1.12a/generateDS.py", line 3993, in main 
     189            processIncludes, superModule=superModule) 
     190          File "/home/Pete/generateDS-1.12a/generateDS.py", line 3909, in parseAndGenerate 
     191            root.annotate() 
     192        AttributeError: 'NoneType' object has no attribute 'annotate' 
     193 
     194 
     195Other possibilities 
     196===================== 
     197 
     198* http://www.devx.com/ibm/Article/20261 
     199* http://mail.python.org/pipermail/xml-sig/2002-April/007559.html 
     200* http://pywebsvcs.sourceforge.net/ 
  • 1dwg/trunk/doc/source/conf.py

    r247 r250  
    9494# a list of builtin themes. 
    9595html_theme = 'default' 
     96html_theme = 'sphinxdoc' 
    9697 
    9798# Theme options are theme-specific and customize the look and feel of a theme 
  • 1dwg/trunk/doc/source/overview.rst

    r244 r250  
    213213 
    214214 
    215 Converting data into the XML format 
    216 ===================================== 
     215.. _XmlWriter: 
     216 
     217Converting data into the XML format: *XmlWriter* 
     218==================================================== 
    217219 
    218220.. index:: ! xmlWriter 
     
    241243======================================== 
    242244 
     245.. _cansas1d.xsd: 
     246 
    243247XML Schema 
    244248------------- 
    245249 
    246 The *cansas1d.xsd* :index:`XML Schema` (http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd) 
     250The *cansas1d.xsd* :index:`XML Schema`  
     251(http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd) 
    247252defines the rules for the XML file format and is used to 
    248253validate any XML file for adherence to the format. 
  • 1dwg/trunk/doc/source/specification.rst

    r241 r250  
    11.. $Id$ 
     2 
     3.. index:: ! cansas1d/1.1 standard 
     4 
     5.. _specification: 
    26 
    37================= 
     
    1115below. 
    1216 
     17This is the definitive specification of *cansas1d/1.1*, 
     18the canSAS standard format for storing small-angle 
     19scattering data in XML files. 
     20The standard is defined using the rules of XML Schema 
     21(http://www.w3.org/XML/Schema). 
     22 
     23.. index:: ! XML; well-formed 
     24 
     25.. index:: 
     26        single: cansas1d/1.1 standard 
     27        single: validation 
     28 
     29Note that the cansas1d/1.1 XML data files must adhere to the  
     30XML rules which includes being well-formed 
     31(including the use of closing tags).  [#]_ 
     32Files that can be validated  against :ref:`cansas1d.xsd` 
     33(http://svn.smallangles.net/trac/canSAS/browser/1dwg/trunk/cansas1d.xsd) 
     34are deemed to be valid cansas1d/1.1 data files. 
     35 
     36.. [#] For example, see http://www.w3schools.com/xmL/xml_syntax.asp 
     37        for an explanation of the XML syntax. 
     38 
     39In this document, curly braces, *{}*, are used to 
     40indicate text that is supplied by the user.  Such as, an attribute 
     41may be written 
     42 
     43    name={text} 
     44 
     45and this means that the  
     46user would replace *{text}* with text that gives, 
     47in this example, a name such as *final detector*. 
     48Thus resulting in:: 
     49 
     50    name="final detector"  
     51 
     52which is a well-formed XML attribute. 
     53 
     54.. index:: element; {any} 
     55 
     56Another example is an instance of the :ref:`{any}` 
     57element.  Suppose one had analysis data, then *{any}* 
     58would be replaced  
     59with *analysis* and the element might look like this:: 
     60 
     61        <analysis> 
     62           ... analysis content goes here ... 
     63        </analysis> 
     64 
     65 
     66.. rubric:: Contents 
    1367 
    1468.. toctree:: 
Note: See TracChangeset for help on using the changeset viewer.