Changeset 4198

Timestamp:

Dec 9, 2019 2:30:49 PM (3 years ago)

Author:

toby

Message:

doc improvements; new scripting options (rev. sequential & set background file)

Location:

trunk

Files:

• GSASIIIO.py (modified) (1 diff)
• GSASIIdataGUI.py (modified) (4 diffs)
• GSASIIobj.py (modified) (25 diffs)
• GSASIIscriptable.py (modified) (10 diffs)
• docs/source/conf.py (modified) (1 diff)

trunk/GSASIIIO.py

@@ -1531 +1531 @@
         the active histogram being exported.
         '''
+        self.G2frame.CheckNotebook()
         self.parmDict = {}
         self.sigDict = {}

trunk/GSASIIdataGUI.py

@@ -417 +417 @@
 ################################################################################
 class GSASII(wx.Frame):
-    '''Define the main GSAS-II frame and its associated menu items
-    '''
+    '''Define the main GSAS-II frame and its associated menu items.
+
+    :param parent: reference to parent application
+
+    '''                
     def MenuBinding(self,event):
         '''Called when a menu is clicked upon; looks up the binding in table
@@ -438 +441 @@
     
     def _Add_FileMenuItems(self, parent):
+        '''Add items to File menu
+        '''
         item = parent.Append(wx.ID_ANY,'&Open project...\tCtrl+O','Open a GSAS-II project file (*.gpx)')            
         self.Bind(wx.EVT_MENU, self.OnFileOpen, id=item.GetId())
@@ -471 +476 @@
         
     def _Add_DataMenuItems(self,parent):
+        '''Add items to Data menu
+        '''
         # item = parent.Append(
         #     help='',id=wx.ID_ANY,
@@ -577 +584 @@
         
     def PreviewFile(self,filename):
-        'confirm we have the right file'
+        'utility to confirm we have the right file'
         fp = open(filename,'r')
         rdmsg = u'File '+ filename +u' begins:\n\n'

trunk/GSASIIobj.py

@@ -16 +16 @@
 as provides misc. support routines.
 
-Constraints Tree Item
-----------------------
-
 .. _Constraints_table:
 
@@ -24 +21 @@
    single: Constraints object description
    single: Data object descriptions; Constraints
+
+Constraints Tree Item
+----------------------
 
 Constraints are stored in a dict, separated into groups.
@@ -97 +97 @@
       :math:`newvar = m_1 \\times var_1 + m_2 \\times var_2 + ...`
 
-Covariance Tree Item
---------------------
-
 .. _Covariance_table:
 
@@ -105 +102 @@
    single: Covariance description
    single: Data object descriptions; Covariance
+
+Covariance Tree Item
+--------------------
 
 The Covariance tree item has results from the last least-squares run. They
@@ -140 +140 @@
 =============  ===============  ====================================================
 
-Phase Tree Items
-----------------
-
 .. _Phase_table:
 
@@ -148 +145 @@
    single: Phase object description
    single: Data object descriptions; Phase
+
+Phase Tree Items
+----------------
 
 Phase information is stored in the GSAS-II data tree as children of the
@@ -297 +297 @@
 ==========  ===============  ====================================================
 
-Rigid Body Objects
-------------------
-
 .. _RBData_table:
 
@@ -305 +302 @@
    single: Rigid Body Data description
    single: Data object descriptions; Rigid Body Data
+
+Rigid Body Objects
+------------------
 
 Rigid body descriptions are available for two types of rigid bodies: 'Vector'
@@ -345 +345 @@
 ==========  ===============  ====================================================
 
-Space Group Objects
--------------------
-
 .. _SGData_table:
 
@@ -353 +350 @@
    single: Space Group Data description
    single: Data object descriptions; Space Group Data
+
+Space Group Objects
+-------------------
 
 Space groups are interpreted by :func:`GSASIIspc.SpcGroup`
@@ -416 +416 @@
 
 
-Atom Records
-------------
-
 .. _Atoms_table:
 
@@ -425 +422 @@
    single: Data object descriptions; Atoms record
 
+Atom Records
+------------
 
 If ``phasedict`` points to the phase information in the data tree, then
@@ -455 +454 @@
 ==============   ====================================================
 
-Drawing Atom Records
---------------------
-
 .. _Drawing_atoms_table:
 
@@ -464 +460 @@
    single: Data object descriptions; Drawing atoms record
 
+Drawing Atom Records
+--------------------
 
 If ``phasedict`` points to the phase information in the data tree, then
@@ -493 +491 @@
 ==============   ====================================================
 
-Powder Diffraction Tree Items
------------------------------
-
 .. _Powder_table:
 
@@ -501 +496 @@
    single: Powder data object description
    single: Data object descriptions; Powder Data
+
+Powder Diffraction Tree Items
+-----------------------------
 
 Every powder diffraction histogram is stored in the GSAS-II data tree
@@ -627 +625 @@
 ======================  ===============  ====================================================
 
-Powder Reflection Data Structure
---------------------------------
-
 .. _PowderRefl_table:
 
@@ -635 +630 @@
    single: Powder reflection object description
    single: Data object descriptions; Powder Reflections
+
+Powder Reflection Data Structure
+--------------------------------
 
 For every phase in a histogram, the ``Reflection Lists`` value is a dict
@@ -656 +654 @@
 ==========  ====================================================
 
-Single Crystal Tree Items
--------------------------
-
 .. _Xtal_table:
 
@@ -664 +659 @@
    single: Single Crystal data object description
    single: Data object descriptions; Single crystal data
+
+Single Crystal Tree Items
+-------------------------
 
 Every single crystal diffraction histogram is stored in the GSAS-II data tree
@@ -714 +712 @@
 ======================  ===============  ====================================================
 
-Single Crystal Reflection Data Structure
-----------------------------------------
-
 .. _XtalRefl_table:
 
@@ -722 +717 @@
    single: Single Crystal reflection object description
    single: Data object descriptions; Single Crystal Reflections
+
+Single Crystal Reflection Data Structure
+----------------------------------------
 
 For every single crystal a histogram, the ``'Data'`` item contains
@@ -744 +742 @@
 ==========  ====================================================
 
-Image Data Structure
---------------------
-
 .. _Image_table:
 
@@ -752 +747 @@
    image: Image data object description
    image: Image object descriptions
+
+Image Data Structure
+--------------------
 
 Every 2-dimensional image is stored in the GSAS-II data tree
@@ -871 +869 @@
 ======================  ======================  ====================================================
 
+.. _parmDict_table:
+
+.. index::
+   single: Parameter dictionary
+
 Parameter Dictionary
 -------------------------
-
-.. _parmDict_table:
-
-.. index::
-   single: Parameter dictionary
 
 The parameter dictionary contains all of the variable parameters for the refinement.

trunk/GSASIIscriptable.py

@@ -486 +486 @@
 \                     type                  The background model, e.g. 'chebyschev'
 \                     refine                The value of the refine flag, boolean
-\                     no. coeffs            Number of coefficients to use, integer
+\                     'no. coeffs'          Number of coefficients to use, integer
 \                     coeffs                List of floats, literal values for background
 \                     FixedPoints           List of (2-theta, intensity) values for fixed points
-\                     fit fixed points      If True, triggers a fit to the fixed points to
+\                     'fit fixed points'    If True, triggers a fit to the fixed points to
                                             be calculated. It is calculated when this key is
                                             detected, regardless of calls to refine.
-                      peaks                 Specifies a set of flags for refining 
+\                     peaks                 Specifies a set of flags for refining 
                                             background peaks as a nested list. There may
                                             be an item for each defined background peak
@@ -1814 +1814 @@
 
 class G2Project(G2ObjectWrapper):    
-    """Represents an entire GSAS-II project.
+    """Represents an entire GSAS-II project. The object contains these 
+    class variables:
+
+     * G2Project.filename: contains the .gpx filename
+     * G2Project.names: contains the contents of the project "tree" as a list 
+       of lists. Each top-level entry in the tree is an item in the list. The 
+       name of the top-level item is the first item in the inner list. Children
+       of that item, if any, are subsequent entries in that list.
+     * G2Project.data: contains the entire project as a dict. The keys 
+       for the dict are the top-level names in the project tree (initial items
+       in the G2Project.names inner lists) and each top-level item is stored
+       as a dict. 
+
+         * The contents of Top-level entries will be found in the item 
+           named 'data', as an example, ``G2Project.data['Notebook']['data']`` 
+
+         * The contents of child entries will be found in the item
+           using the names of the parent and child, for example 
+           ``G2Project.data['Phases']['NaCl']``
 
     :param str gpxfile: Existing .gpx file to be loaded. If nonexistent,
@@ -3021 +3039 @@
             * cycles: the maximum number of cycles (returns int)
             * sequential: the histograms used for a sequential refinement as a list
-              of histogram names or an empty list when in non-sequential mode. 
+              of histogram names or an empty list when in non-sequential mode.
+            * Reverse Seq: returns True or False. True indicates that fitting of the
+              sequence of histograms proceeds in reversed order.
             * seqCopy: returns True or False. True indicates that results from 
               each sequential fit are used as the starting point for the next
@@ -3035 +3055 @@
         elif control == 'sequential':
             return self.data['Controls']['data']['Seq Data']
+        elif control == 'Reverse Seq':
+            return self.data['Controls']['data']['Reverse Seq']
         elif control in self.data['Controls']['data']:
             return self.data['Controls']['data'][control]
@@ -3059 +3081 @@
               the starting point for the next. After each fit is is set to False. 
               Ignored for non-sequential fits. 
+            * Reverse Seq: when True, sequential refinement is performed on the
+              reversed list of histograms.
 
         .. seealso::
@@ -3067 +3091 @@
         elif control == 'seqCopy':
             self.data['Controls']['data']['Copy2Next'] = bool(value)
+        elif control == 'Reverse Seq':
+            self.data['Controls']['data']['Reverse Seq'] = bool(value)
         elif control == 'sequential':
             histlist = []
@@ -3291 +3317 @@
 
 class G2PwdrData(G2ObjectWrapper):
-    """Wraps a Powder Data Histogram."""
+    """Wraps a Powder Data Histogram. 
+    The object contains these class variables:
+
+        * G2PwdrData.proj: contains a reference to the :class:`G2Project`
+          object that contains this histogram 
+        * G2PwdrData.name: contains the name of the histogram
+        * G2PwdrData.data: contains the histogram's associated data in a dict,
+          as documented for the :ref:`Powder Diffraction Tree<Powder_table>`.
+          The actual histogram values are contained in the 'data' dict item,
+          as documented for Data. 
+
+    """
     def __init__(self, data, proj, name):
         self.data = data
@@ -3587 +3624 @@
         return self['data'][0].get('wR')
 
+    def _decodeHist(self,hist):
+        '''Convert a histogram reference to a histogram name string
+        '''
+        if isinstance(hist, G2PwdrData):
+            return hist.name
+        elif hist in [h.name for h in self.proj.histograms()]:
+            return hist
+        elif type(hist) is int:
+            return self.proj.histograms()[hist].name
+        else:
+            raise G2ScriptException("Invalid histogram reference: "+str(hist))
+        
+    def set_background(self, key, value):
+        '''Set background parameters (this serves a similar function as in 
+        :meth:`set_refinements`, but with a simplified interface). 
+
+        :param str key: a string that defines the background parameter that will 
+           be changed. Must appear in the table below.
+
+           =================   ==============   ===========================================
+           key name            type of value     meaning of value
+           =================   ==============   ===========================================
+           fixedHist           int, str,         reference to a histogram in the current
+                               None or           project or None to remove the reference.
+                               G2PwdrData        
+           fixedFileMult       float             multiplier applied to intensities in 
+                                                 the background histogram where a value 
+                                                 of -1.0 means full subtraction of 
+                                                 the background histogram.
+           =================   ==============   ===========================================
+
+        :param value: a value to set the selected background parameter. The meaning 
+           and type for this parameter is listed in the table above.
+
+        '''
+        bkgPrms, bkgDict = self.data['Background']
+        if key == 'fixedHist':
+            if value is None:
+                bkgDict['background PWDR'][0] = ''
+                return
+            bkgDict['background PWDR'][0] = self._decodeHist(value)
+        elif key == 'fixedFileMult':
+            bkgDict['background PWDR'][1] = float(value)
+        else:
+            raise ValueError("Invalid key in set_background:", key)
+        
     def set_refinements(self, refs):
         """Sets the histogram refinement parameter 'key' to the specification 'value'.
@@ -3918 +4001 @@
 class G2Phase(G2ObjectWrapper):
     """A wrapper object around a given phase.
+    The object contains these class variables:
+
+        * G2Phase.proj: contains a reference to the :class:`G2Project`
+          object that contains this phase 
+        * G2Phase.name: contains the name of the phase
+        * G2Phase.data: contains the phases's associated data in a dict,
+          as documented for the :ref:`Phase Tree items<Phase_table>`.
 
     Author: Jackson O'Donnell (jacksonhodonnell .at. gmail.com)
@@ -5024 +5114 @@
     calls to :meth:`G2Project.add_image` or :meth:`G2Project.images`. 
     Scripts will not use ``G2Image()`` to call :meth:`G2Image.__init__` directly. 
+    The object contains these class variables:
+
+        * G2Image.proj: contains a reference to the :class:`G2Project`
+          object that contains this image 
+        * G2Image.name: contains the name of the image
+        * G2Image.data: contains the image's associated data in a dict,
+          as documented for the :ref:`Image Data Structure<Image_table>`.
 
     Example use of G2Image:

trunk/docs/source/conf.py

@@ -18 +18 @@
     #def __getattr__(cls, name):
     #    return wx()
-    Menu = Panel = Dialog = CheckBox = Choice = ComboBox = object
+    Frame = Menu = Panel = Dialog = CheckBox = Choice = ComboBox = object
     Button = PyValidator = TextCtrl = TreeCtrl = object
     DEFAULT_DIALOG_STYLE = RESIZE_BORDER = CENTRE = OK = CANCEL = True