Changeset 3187

Timestamp:

Dec 10, 2017 10:14:04 AM (5 years ago)

Author:

toby

Message:

misc docs cleanups; add 1-ID metadata reader & new config variable

Location:

trunk

Files:

• GSASIIIO.py (modified) (5 diffs)
• GSASIIctrlGUI.py (modified) (1 diff)
• GSASIIdataGUI.py (modified) (1 diff)
• GSASIImath.py (modified) (4 diffs)
• GSASIIobj.py (modified) (1 diff)
• GSASIIscriptable.py (modified) (3 diffs)
• config_example.py (modified) (1 diff)
• docs/source/GSASIIscripts.rst (modified) (2 diffs)
• docs/source/GSASIIutil.rst (modified) (2 diffs)
• docs/source/index.rst (modified) (1 diff)
• makeTutorial.py (modified) (1 diff)

trunk/GSASIIIO.py

@@ -39 +39 @@
 import sys
 import re
+import glob
 import random as ran
 import GSASIIpath
@@ -363 +364 @@
 
 def GetImageData(G2frame,imagefile,imageOnly=False,ImageTag=None,FormatName=''):
-    '''Read a single image with an image importer. 
+    '''Read a single image with an image importer. This is called to reread an image
+    after it has already been imported with :meth:`GSASIIdataGUI.GSASII.OnImportGeneric`
+    (or :func:`ReadImages` in Auto Integration) so it is not necessary to reload metadata.
 
     :param wx.Frame G2frame: main GSAS-II Frame and data object.
@@ -439 +442 @@
     using image importers. Called only in :meth:`AutoIntFrame.OnTimerLoop`.
 
+    ToDo: Images are most commonly read in :meth:`GSASIIdataGUI.GSASII.OnImportGeneric`
+    which is called from :meth:`GSASIIdataGUI.GSASII.OnImportImage`
+    it would be good if these routines used a common code core so that changes need to
+    be made in only one place.
+
     :param wx.Frame G2frame: main GSAS-II Frame and data object.
     :param str imagefile: name of image file 
@@ -492 +500 @@
                     rd.Image = rd.Image.T
                 rd.Data['ImageTag'] = rd.repeatcount
+                if GSASIIpath.GetConfigValue('Image_1IDmetadata'):
+                    rd.readfilename = imagefile
+                    Get1IDMetadata(rd)
                 LoadImage2Tree(imagefile,G2frame,rd.Comments,rd.Data,rd.Npix,rd.Image)
                 repeat = rd.repeat
@@ -2135 +2146 @@
     return Layer
 
+def Read1IDpar(imagefile):
+    '''Reads image metadata from a 1-ID style .par file from the same directory
+    as the image. The .par file has any number of columns separated by spaces.
+    As an index to the .par file a second label file must be specified with the
+    same file name as the .par file but the extension must be .XXX_lbls (where
+    .XXX is the extension of the image) or if that is not present extension
+    .lbls
+
+    :param str imagefile: the full name of the image file (with directory and extension)
+
+    :returns: a dict with parameter values. Named parameters will have the type based on
+       the specified Python function, named columns will be character strings
+    
+    The contents of the label file will look like this::
+    
+        # define keywords
+        filename:lambda x,y: "{}_{:0>6}".format(x,y)|33,34
+        distance: float | 75
+        wavelength:lambda keV: 12.398425/float(keV)|9
+        pixelSize:lambda x: [74.8, 74.8]|0
+        ISOlikeDate: lambda dow,m,d,t,y:"{}-{}-{}T{} ({})".format(y,m,d,t,dow)|0,1,2,3,4
+        # define other variables
+        0:day
+        1:month
+        2:date
+        3:time
+        4:year
+        7:I_ring
+
+    This file contains three types of lines in any order.
+     * Named parameters are evaluated with user-supplied Python code (see
+       subsequent information). Specific named parameters are used 
+       to determine values that are used for image interpretation (see table,
+       below). Any others are copied to the Comments subsection of the Image
+       tree item.
+     * Column labels are defined with a column number (integer) followed by
+       a colon (:) and a label to be assigned to that column. All labeled
+       columns are copied to the Image's Comments subsection.
+     * Comments are any line that does not contain a colon.
+
+    Note that columns are numbered starting at zero. 
+
+    Any named parameter may be defined provided it is not a valid integer,
+    but the named parameters in the table have special meanings, as descibed.
+    The parameter name is followed by a colon. After the colon, specify
+    Python code that defines or specifies a function that will be called to
+    generate a value for that parameter. After that code, supply a vertical
+    bar (|) and then a list of one more more columns that will be supplied
+    as arguments to that function. The examples above are discussed below:
+
+    ``filename:lambda x,y: "{}_{:0>6}".format(x,y)|33,34``
+        Here the function to be used is defined with a lambda statement:
+        
+          lambda x,y: "{}_{:0>6}".format(x,y)
+
+        This function will use the format function to create a file name from the
+        contents of columns 33 and 34. The first parameter (x, col. 33) is inserted directly into
+        the file name, followed by a underscore (_), followed by the second parameter (y, col. 34),
+        which will be left-padded with zeros to six characters (format directive ``:0>6``).
+        
+    ``distance: float | 75``
+        Here the contents of column 75 will be converted to a floating point number
+        by calling float on it. Note that the spaces here are ignored.
+        
+    ``wavelength:lambda keV: 12.398425/float(keV)|9``
+        Here we define an algebraic expression to convert an energy in keV to a
+        wavelength and pass the contents of column 9 as that input energy
+        
+    ``pixelSize:lambda x: [74.8, 74.8]|0``
+        In this case the pixel size is a constant (a list of two numbers). The first
+        column is passed as an argument as at least one argument is required, but that
+        value is not used in the expression.
+
+     ``ISOlikeDate: lambda dow,m,d,t,y:"{}-{}-{}T{} ({})".format(y,m,d,t,dow)|0,1,2,3,4``
+        This example defines a parameter that takes items in the first five columns
+        and formats them in a different way. This parameter is not one of the pre-defined
+        parameter names below. Some external code could be used to change the month string
+        (argument ``m``) to a integer from 1 to 12. 
+            
+    **Pre-defined parameter names**
+    
+    =============  =========  ========  ====================================================
+     keyword       required    type      Description
+    =============  =========  ========  ====================================================
+       filename    yes         str      generates the file name prefix for the matching image
+                                        file (MyImage001 for file /tmp/MyImage001.tif).
+     polarization  no         float     generates the polarization expected based on the
+                                        monochromator angle, defaults to 0.99.
+       center      no         list of   generates the approximate beam center on the detector
+                              2 floats  in mm, such as [204.8, 204.8].
+       distance    yes        float     generates the distance from the sample to the detector
+                                        in mm
+       pixelSize   no         list of   generates the size of the pixels in microns such as
+                              2 floats  [200.0, 200.0]. 
+       wavelength  yes        float     generates the wavelength in Angstroms
+    =============  =========  ========  ====================================================
+
+    
+    '''
+    dir,fil = os.path.split(os.path.abspath(imagefile))
+    imageName,ext = os.path.splitext(fil)
+    parfiles = glob.glob(os.path.join(dir,'*.par'))
+    if len(parfiles) == 0:
+        print('Sorry, No 1-ID .par file found in '+dir)
+        return {}
+    for parFil in parfiles: # loop over all .par files (hope just 1) in image dir until image is found
+        parRoot = os.path.splitext(parFil)[0]
+        for e in (ext+'_lbls','.lbls'):
+            if os.path.exists(parRoot+e):
+                lblFil = parRoot+e
+                break
+        else:
+            print('Warning: No labels definitions found for '+parFil)
+            return {}
+        fp = open(lblFil,'Ur')         # read column labels
+        lbldict = {}
+        fmt = ""
+        keyExp = {}
+        keyCols = {}
+        for line in fp: # read label definitions
+            items = line.strip().split(':')
+            if len(items) < 2: continue # no colon, line is a comment
+            # is this line a definition for a named parameter?
+            key = items[0]
+            try: 
+                int(key)
+            except ValueError: # named parameters are not valid numbers
+                items = line.split(':',1)[1].split('|')
+                try:
+                    keyExp[key] = eval(items[0]) # compile the expression
+                    if not callable(keyExp[key]):
+                        raise Exception("Expression not a function")
+                except Exception as msg:
+                    print('Warning: Expression "{}" is not valid for key {}'.format(items[0],key))
+                    print(msg)
+                keyCols[key] = [int(i) for i in items[1].strip().split(',')]
+                continue
+            if len(items) == 2: # simple column definition
+                lbldict[int(items[0])] = items[1]
+        fp.close()
+        if 'filename' not in keyExp:
+            print("Warning: No valid filename expression in {} file, skipping .par".format(lblFil))
+            continue
+        # read the .par, looking for the matching image rootname
+        fp = open(parFil,'Ur')
+        for i,line in enumerate(fp):
+            items = line.strip().split(' ')
+            name = keyExp['filename'](*[items[j] for j in keyCols['filename']])
+            if name == imageName: # got our match, parse the line and finish
+                metadata = {lbldict[i]:items[i] for i in lbldict}
+                metadata.update(
+                    {key:keyExp[key](*[items[j] for j in keyCols[key]]) for key in keyExp})
+                metadata['par file'] = parFil
+                metadata['lbls file'] = lblFil
+                print("Metadata read from {}".format(parFil))
+                return metadata
+        else:
+            print("Image {} not found in {}".format(imageName,parFil))
+            fp.close()
+            continue
+        fp.close()
+    else:
+        print("Warning: No 1-ID metadata for image {}".format(imageName))
+        return {}
+
+def Get1IDMetadata(reader):
+    '''Add 1-ID metadata to an image using a 1-ID .par file using :func:`Read1IDpar`
+    
+    :param reader: a reader object from reading an image
+    
+    '''
+    parParms = Read1IDpar(reader.readfilename)
+    if not parParms: return # check for read failure
+    specialKeys = ('filename',"polarization", "center", "distance", "pixelSize", "wavelength",)
+    reader.Comments = ['Metadata from {} assigned by {}'.format(parParms['par file'],parParms['lbls file'])]
+    for key in parParms:
+        if key in specialKeys+('par file','lbls file'): continue
+        reader.Comments += ["{} = {}".format(key,parParms[key])]
+    if "polarization" in parParms:
+        reader.Data['PolaVal'][0] = parParms["polarization"]
+    else:
+        reader.Data['PolaVal'][0] = 0.99
+    if "center" in parParms:
+        reader.Data['center'] = parParms["center"]
+    if "pixelSize" in parParms:
+        reader.Data['pixelSize'] = parParms["pixelSize"]
+    if "wavelength" in parParms:
+        reader.Data['wavelength'] = parParms['wavelength']
+    else:
+        print('Error: wavelength not defined in {}'.format(parParms['lbls file']))
+    if "distance" in parParms:
+        reader.Data['distance'] = parParms['distance']
+        reader.Data['setdist'] = parParms['distance']
+    else:
+        print('Error: distance not defined in {}'.format(parParms['lbls file']))
+
 if __name__ == '__main__':
     import GSASIIdataGUI

trunk/GSASIIctrlGUI.py

@@ -4559 +4559 @@
     #['ExampleDir', 'ExamplePage.html', 'Example Tutorial Title'],
     )
+'''A catalog of GSAS-II tutorials with headings. This is the master list of GSAS-II tutorials and must be updated when tutorials are
+added. Each item has either one or three items. 
+Titles are single item in a list or tuple. Tutorials have three items: (a) the name of the directory,
+(b) the name of the web page and (c) a title for the tutorial. 
+Tutorials that depend on a previous tutorial being completed should have the title for
+the tutorial indented by five spaces.
+
+Note that :data:`tutorialCatalog` is generated from this tuple. 
+Also see :mod:`makeTutorial` which is used to read this and create a web page.
+'''
+
+#A catalog of GSAS-II tutorials generated from the table in :data:`tutorialIndex`
 tutorialCatalog = [l for l in tutorialIndex if len(l) == 3]
 

trunk/GSASIIdataGUI.py

@@ -783 +783 @@
                             if rd.sumfile:
                                 rd.readfilename = rd.sumfile
+                            if GSASIIpath.GetConfigValue('Image_1IDmetadata'):
+                                G2IO.Get1IDMetadata(rd)
                             G2IO.LoadImage2Tree(rd.readfilename,self,rd.Comments,rd.Data,rd.Npix,rd.Image)
                             rd_list.append(True) # save a stub the result before it is written over

trunk/GSASIImath.py

@@ -88 +88 @@
 
     References: 
-    .. [1] G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando,
-           FL, Academic Press, Inc., 1980, pp. 139-142.
+    .. [1] G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pp. 139-142.
 
     """
@@ -874 +873 @@
     :param array Y: normalized vector
     
-    :returns: array M: transformation matrix 
+    :returns: array M: transformation matrix
+    
     use as XYZ' = np.inner(M,XYZ) where XYZ are Cartesian
     
@@ -4127 +4127 @@
            lower=-100, upper=100, dwell=50, slope=0.9,ranStart=False,
            ranRange=0.10,autoRan=False,dlg=None):
-    ''' Scipy license:
-        Copyright (c) 2001, 2002 Enthought, Inc.
-    All rights reserved.
-    
-    Copyright (c) 2003-2016 SciPy Developers.
-    All rights reserved.
-    
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions are met:
-    
-      a. Redistributions of source code must retain the above copyright notice,
-         this list of conditions and the following disclaimer.
-      b. Redistributions in binary form must reproduce the above copyright
-         notice, this list of conditions and the following disclaimer in the
-         documentation and/or other materials provided with the distribution.
-      c. Neither the name of Enthought nor the names of the SciPy Developers
-         may be used to endorse or promote products derived from this software
-         without specific prior written permission.
-    '''
-
     """Minimize a function using simulated annealing.
 
@@ -4238 +4218 @@
         T_new = T0 * exp(-c * k**quench)
 
-
     """
+    
+    ''' Scipy license:
+        Copyright (c) 2001, 2002 Enthought, Inc.
+    All rights reserved.
+    
+    Copyright (c) 2003-2016 SciPy Developers.
+    All rights reserved.
+    
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+    
+      a. Redistributions of source code must retain the above copyright notice,
+         this list of conditions and the following disclaimer.
+      b. Redistributions in binary form must reproduce the above copyright
+         notice, this list of conditions and the following disclaimer in the
+         documentation and/or other materials provided with the distribution.
+      c. Neither the name of Enthought nor the names of the SciPy Developers
+         may be used to endorse or promote products derived from this software
+         without specific prior written permission.
+    '''
     x0 = asarray(x0)
     lower = asarray(lower)

trunk/GSASIIobj.py

@@ -2738 +2738 @@
        tim0.start('in section 1')
        tim0.start('in section 2')
+       
     etc. (Note that each section should have a unique label.)
 

trunk/GSASIIscriptable.py

@@ -9 +9 @@
 ########### SVN repository information ###################
 """
-*GSASIIscriptable: Scripting Tools*
-======================================
+*GSASIIscriptable: Scripting Interface*
+=======================================
 
 Routines for reading, writing, modifying and creating GSAS-II project (.gpx) files.
@@ -312 +312 @@
 import datetime as dt
 import sys
-import cPickle
+import platform
+if '2' in platform.python_version_tuple()[0]:
+    import cPickle
+else:
+    import _pickle as cPickle
 import imp
 import copy
@@ -1326 +1330 @@
         if outputnames:
             if len(refinements) != len(outputnames):
-                raise ValueError("Should have same number of outuputs to"
+                raise ValueError("Should have same number of outputs to"
                                  "refinements")
         else:

trunk/config_example.py

@@ -170 +170 @@
 Show_timing = False
 '''If True, shows various timing results.'''
+
+Image_1IDmetadata = False
+'''When True, when images are read, GSAS-II will read metadata from a 1-ID style
+.par and .lbls (or .lbls_EXT) file.
+'''

trunk/docs/source/GSASIIscripts.rst

@@ -1 @@
-.. automodule:: GSASIIscriptable
-    :members: 
-
 *GSAS-II Misc Scripts*
 ======================
@@ -20 +17 @@
     :members: 
 
+.. automodule:: makeLinux
+    :members: 
+
+.. automodule:: makeTutorial
+    :members: 
+
 .. automodule:: unit_tests
     :members: 

trunk/docs/source/GSASIIutil.rst

@@ -1 +1 @@
 *GSAS-II Utility Modules*
 =========================
-
-.. automodule:: GSASIIdata
-    :members: 
 
 .. automodule:: GSASIIpath
@@ -21 +18 @@
 
 .. automodule:: GSASIIspc
+    :members: 
+
+.. automodule:: GSASIIdata
+    :members: 
+
+.. automodule:: GSASIIfiles
+    :members: 
+
+.. automodule:: GSASIImpsubs
     :members: 
 

trunk/docs/source/index.rst

@@ -20 +20 @@
   GSASIIpwd.rst
   SAS.rst
+  GSASIIscriptable.rst
   GSASIIscripts.rst
   exports.rst

trunk/makeTutorial.py

@@ -1 @@
-# create an HTML page from the tutorials in GSASIIctrlGUI.tutorialCatalog
+# -*- coding: utf-8 -*-
+#makeTutorial.py
+########### SVN repository information ###################
+# $Date: $
+# $Author: toby $
+# $Revision: 3167 $
+# $URL: $
+# $Id: $
+########### SVN repository information ###################
+'''
+*makeTutorial: Make Tutorial Web Page*
+---------------------------------------------
+
+Creates an HTML page (``GSASII/help/Tutorials.html``) listing all the tutorials in
+:data:`GSASIIctrlGUI.tutorialIndex`. Run this after adding a new tutorial to that
+index.
+'''
 
 from __future__ import print_function