Ignore:
Timestamp:
Jun 11, 2023 1:56:25 PM (6 months ago)
Author:
toby
Message:

Scripting: add shortcut support; Pixel masking; optimize integration; comment G2image

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/docs/source/GSASIIscriptable.rst

    r5572 r5611  
    1 =======================================
    2 *GSASIIscriptable: Scripting Interface*
    3 =======================================
     1=========================================
     2 *GSASIIscriptable: Scripting Interface*
     3=========================================
    44
    55
    66*Summary/Contents*
    7 ==================================================
     7==================
    88
    99Routines to use an increasing amount of GSAS-II's capabilities from scripts,
    1010without use of the graphical user interface (GUI). GSASIIscriptable can create and access
    1111GSAS-II project (.gpx) files and can directly perform image handling and refinements. 
    12 The module defines wrapper classes (inheriting from :class:`G2ObjectWrapper`) for a growing number
     12The module defines wrapper classes (inheriting from :class:`~GSASIIscriptable.G2ObjectWrapper`) for a growing number
    1313of data tree items.
    1414
    … …  
    1717used is via Python scripts that
    1818call the module's application interface (API), see API summary that follows or the :ref:`API`
    19 section. The command-line mode
     19section.
     20
     21While the command-line mode
    2022provides access a number of features without writing Python scripts
    21 via shell/batch commands (see :ref:`CommandlineInterface`) but this
     23via shell/batch commands (see :ref:`CommandlineInterface`), use in practice
     24seems somewhat clumsy. Command-line mode
    2225is no longer being developed and its use is discouraged.
    2326
    2427.. contents:: Section Contents
    2528
     29Installation of GSASIIscriptable
     30================================
     31
     32GSASIIscriptable is included as part of a standard GSAS-II installation that includes the GSAS-II GUI (as described in the `installation instructions <https://subversion.xray.aps.anl.gov/trac/pyGSAS#Installationinstructions>`_). People who will will use scripting extensively will still need access to the GUI
     33for some activities, since the scripting API has not yet been extended to all
     34features of GSAS-II and even if that is ever completed, there will still be some things that GSAS-II does with the GUI would be almost impossible to implement without a interactive graphical view of the data.
     35
     36Nonetheless, there may be times where it does make sense to install GSAS-II without all of the GUI components, for example on a compute server.
     37The minimal requirements for use of GSASIIscriptable are only Python, numpy and scipy, but additional optional requirements are described in
     38the :ref:`ScriptingRequirements`, which also provides some installation instructions.
     39
     40In a standard GSAS-II installation, no changes are made to Python. When the GUI is invoked, a small script or Windows batch file is used to start GSAS-II inside Python. When
     41GSASIIscriptable is used, Python must be provided with the location of the GSAS-II files. There are two ways this can be done:
     42
     43* define the GSAS-II installation location in the Python ``sys.path``, or
     44* install a reference to GSAS-II inside Python.
     45
     46The latter method requires an extra installation step, but has the advantage that
     47it allows writing portable GSAS-II scripts. This is discussed further in the
     48:ref:`ScriptingShortcut` section of this chapter.
    2649
    2750Application Interface (API) Summary
    28 ==================================================
     51===================================
    2952This section of the documentation provides an overview to API, with full documentation
    3053in the :ref:`API` section. The typical API use will be with a Python script, such as
    … …  
    3255summarized below.
    3356
    34 Overview of Classes 
    35 ---------------------
     57Overview of Classes
     58-------------------
    3659
    3760.. tabularcolumns:: |l|p{4in}|
    3861
    39 ===============================    ===============================================================================================================
    40 class                              Encapsulates
    41 ===============================    ===============================================================================================================
    42 :class:`G2Project`                  A GSAS-II project file, provides references to objects below,
    43                                     each corresponding to a tree item
    44                                     (exception is :class:`G2AtomRecord`)
    45 :class:`G2Phase`                    Provides phase information access
    46                                     (also provides access to atom info via :class:`G2AtomRecord`)
    47 :class:`G2AtomRecord`               Access to an atom within a phase
    48 :class:`G2PwdrData`                 Access to powder histogram info
    49 :class:`G2Image`                    Access to image info
    50 :class:`G2PDF`                      PDF histogram info
    51 :class:`G2SeqRefRes`                The sequential results table
    52 ===============================    ===============================================================================================================
     62=======================================   ===============================================================================================================
     63class                                      Encapsulated by class
     64=======================================   ===============================================================================================================
     65:class:`~GSASIIscriptable.G2Project`       A GSAS-II project file; provides references to objects below,
     66                                           each corresponding to a tree item
     67                                           (exception is :class:`~GSASIIscriptable.G2AtomRecord`)
     68:class:`~GSASIIscriptable.G2Phase`         Provides phase information access
     69                                           (also provides access to atom info via :class:`~GSASIIscriptable.G2AtomRecord`)
     70:class:`~GSASIIscriptable.G2AtomRecord`               Access to an atom within a phase
     71:class:`~GSASIIscriptable.G2PwdrData`                 Access to powder histogram info
     72:class:`~GSASIIscriptable.G2Image`                    Access to image info
     73:class:`~GSASIIscriptable.G2PDF`                      PDF histogram info
     74:class:`~GSASIIscriptable.G2SeqRefRes`                The sequential results table
     75=======================================   ===============================================================================================================
    5376
    5477Functions
    55 ---------------------
    56 
    57 A small amount of the Scriptable code does not require use of objects.
     78---------
     79
     80A small number of Scriptable routines do not require use of objects.
    5881
    5982.. tabularcolumns:: |l|p{4in}|
     83
     84===================================================   ===============================================================================================================
     85method                                                Use
     86===================================================   ===============================================================================================================
     87:func:`~GSASIIscriptable.GenerateReflections`         Generates a list of unique powder reflections
     88:func:`~GSASIIscriptable.SetPrintLevel`               Sets the amount of output generated when running a script
     89:func:`~GSASIIscriptable.installScriptingShortcut`    Installs GSASIIscriptable within Python as G2script
     90===================================================   ===============================================================================================================
     91
     92Class :class:`~GSASIIscriptable.G2Project`
     93---------------------------------------------
     94
     95  All GSASIIscriptable scripts will need to create a :class:`~GSASIIscriptable.G2Project` object
     96  either for a new GSAS-II project or to read in an existing project (.gpx) file.
     97  The most commonly used routines in this object are:
     98
     99.. tabularcolumns:: |l|p{3.in}|
     100
     101====================================================================    ===============================================================================================================
     102method                                                                  Use
     103====================================================================    ===============================================================================================================
     104:meth:`~GSASIIscriptable.G2Project.save`                                Writes the current project to disk.
     105
     106:meth:`~GSASIIscriptable.G2Project.add_powder_histogram`                Used to read in powder diffraction data into a project file.
     107
     108:meth:`~GSASIIscriptable.G2Project.add_simulated_powder_histogram`      Defines a "dummy" powder diffraction data that will be simulated after a refinement step.
     109
     110:meth:`~GSASIIscriptable.G2Project.add_image`                           Reads in an image into a project.
     111
     112:meth:`~GSASIIscriptable.G2Project.add_phase`                           Adds a phase to a project
     113
     114:meth:`~GSASIIscriptable.G2Project.add_PDF`                             Adds a PDF entry to a project (does not compute it)
     115
     116:meth:`~GSASIIscriptable.G2Project.histograms`                          Provides a list of histograms in the current project, as :class:`~GSASIIscriptable.G2PwdrData` objects
     117
     118:meth:`~GSASIIscriptable.G2Project.phases`                              Provides a list of phases defined in the current project, as :class:`~GSASIIscriptable.G2Phase` objects
     119
     120:meth:`~GSASIIscriptable.G2Project.images`                              Provides a list of images in the current project, as :class:`~GSASIIscriptable.G2Image` objects
     121
     122:meth:`~GSASIIscriptable.G2Project.pdfs`                                Provides a list of PDFs in the current project, as :class:`~GSASIIscriptable.G2PDF` objects
     123
     124:meth:`~GSASIIscriptable.G2Project.seqref`                              Returns a :class:`~GSASIIscriptable.G2SeqRefRes` object if there are Sequential Refinement results
     125
     126:meth:`~GSASIIscriptable.G2Project.do_refinements`                      This is passed a list of dictionaries, where each dict defines a refinement step.
     127                                                                        Passing a list with a single empty dict initiates a refinement with the current
     128                                                                        parameters and flags. A refinement dict sets up a single refinement step
     129                                                                        (as described in :ref:`Project_dicts`). Also see :ref:`Refinement_recipe`.
     130
     131:meth:`~GSASIIscriptable.G2Project.set_refinement`                      This is passed a single dict which is used to set parameters and flags.
     132                                                                        These actions can be performed also in :meth:`~GSASIIscriptable.G2Project.do_refinements`.
     133:meth:`~GSASIIscriptable.G2Project.get_Variable`                        Retrieves the value and esd for a parameter
     134:meth:`~GSASIIscriptable.G2Project.get_Covariance`                      Retrieves values and covariance for a set of refined parameters
     135:meth:`~GSASIIscriptable.G2Project.set_Controls`                        Set overall GSAS-II control settings such as number of cycles and to set up a sequential
     136                                                                        fit. (Also see :meth:`~GSASIIscriptable.G2Project.get_Controls` to read values.)
     137:meth:`~GSASIIscriptable.G2Project.imageMultiDistCalib`                 Performs a global calibration fit with images at multiple distance settings.
     138:meth:`~GSASIIscriptable.G2Project.get_Constraints`                     Retrieves :ref:`constraint definition <Constraint_definitions_table>` entries.
     139:meth:`~GSASIIscriptable.G2Project.add_HoldConstr`                      Adds a hold constraint on one or more variables
     140:meth:`~GSASIIscriptable.G2Project.add_EquivConstr`                     Adds an equivalence constraint on two or more variables
     141:meth:`~GSASIIscriptable.G2Project.add_EqnConstr`                       Adds an equation-type constraint on two or more variables
     142:meth:`~GSASIIscriptable.G2Project.add_NewVarConstr`                    Adds an new variable as a constraint on two or more variables
     143====================================================================    ===============================================================================================================
     144
     145Class :class:`~GSASIIscriptable.G2Phase`
     146-------------------------------------------
     147
     148
     149  Another common object in GSASIIscriptable scripts is :class:`~GSASIIscriptable.G2Phase`, used to encapsulate each phase in a project, with commonly used methods:
     150
     151.. tabularcolumns:: |l|p{3.5in}|
     152
     153========================================================    ===============================================================================================================
     154method                                                      Use
     155========================================================    ===============================================================================================================
     156:meth:`~GSASIIscriptable.G2Phase.set_refinements`           Provides a mechanism to set values and refinement flags for the phase. See :ref:`Phase_parameters_table`
     157                                                            for more details. This information also can be supplied within a call
     158                                                            to :meth:`~GSASIIscriptable.G2Project.do_refinements`
     159                                                            or :meth:`~GSASIIscriptable.G2Project.set_refinement`.
     160:meth:`~GSASIIscriptable.G2Phase.clear_refinements`         Unsets refinement flags for the phase.
     161:meth:`~GSASIIscriptable.G2Phase.set_HAP_refinements`       Provides a mechanism to set values and refinement flags for parameters specific to both this phase and
     162                                                            one of its histograms. See :ref:`HAP_parameters_table`. This information also can be supplied within
     163                                                            a call to :meth:`~GSASIIscriptable.G2Project.do_refinements` or :meth:`~GSASIIscriptable.G2Project.set_refinement`.
     164:meth:`~GSASIIscriptable.G2Phase.clear_HAP_refinements`     Clears refinement flags specific to both this phase and one of its histograms.
     165      :meth:`~GSASIIscriptable.G2Phase.getHAPvalues`        Returns values of parameters specific to both this phase and one of its histograms.
     166:meth:`~GSASIIscriptable.G2Phase.copyHAPvalues`             Copies HAP settings between from one phase/histogram and to other histograms in same phase.
     167:meth:`~GSASIIscriptable.G2Phase.atoms`                     Returns a list of atoms in the phase
     168:meth:`~GSASIIscriptable.G2Phase.atom`                      Returns an atom from its label
     169:meth:`~GSASIIscriptable.G2Phase.histograms`                Returns a list of histograms linked to the phase
     170:meth:`~GSASIIscriptable.G2Phase.get_cell`                  Returns unit cell parameters (also see :meth:`~GSASIIscriptable.G2Phase.get_cell_and_esd`)
     171:meth:`~GSASIIscriptable.G2Phase.export_CIF`                Writes a CIF for the phase
     172:meth:`~GSASIIscriptable.G2Phase.setSampleProfile`          Sets sample broadening parameters
     173:meth:`~GSASIIscriptable.G2Phase.clearDistRestraint`        Clears any previously defined bond distance restraint(s) for the selected phase
     174:meth:`~GSASIIscriptable.G2Phase.addDistRestraint`          Finds and defines new bond distance restraint(s) for the selected phase
     175:meth:`~GSASIIscriptable.G2Phase.setDistRestraintWeight`    Sets the weighting factor for the bond distance restraints
     176========================================================    ===============================================================================================================
     177
     178Class :class:`~GSASIIscriptable.G2PwdrData`
     179---------------------------------------------
     180
     181  Another common object in GSASIIscriptable scripts is :class:`~GSASIIscriptable.G2PwdrData`, which encapsulate each powder diffraction histogram in a project, with commonly used methods:
     182
     183.. tabularcolumns:: |l|p{3.5in}|
     184
     185=======================================================  ===============================================================================================================
     186method                                                     Use
     187=======================================================  ===============================================================================================================
     188:meth:`~GSASIIscriptable.G2PwdrData.set_refinements`     Provides a mechanism to set values and refinement flags for the powder histogram. See
     189                                                         :ref:`Histogram_parameters_table` for details. 
     190:meth:`~GSASIIscriptable.G2PwdrData.clear_refinements`   Unsets refinement flags for the the powder histogram.
     191:meth:`~GSASIIscriptable.G2PwdrData.residuals`           Reports R-factors etc. for the the powder histogram (also see :meth:`~GSASIIscriptable.G2PwdrData.get_wR`)
     192:meth:`~GSASIIscriptable.G2PwdrData.add_back_peak`       Adds a background peak to the histogram. Also see :meth:`~GSASIIscriptable.G2PwdrData.del_back_peak`
     193                                                         and :meth:`~GSASIIscriptable.G2PwdrData.ref_back_peak`.
     194:meth:`~GSASIIscriptable.G2PwdrData.fit_fixed_points`    Fits background to the specified fixed points.
     195:meth:`~GSASIIscriptable.G2PwdrData.getdata`             Provides access to the diffraction data associated with the histogram.
     196:meth:`~GSASIIscriptable.G2PwdrData.reflections`         Provides access to the reflection lists for the histogram.
     197:meth:`~GSASIIscriptable.G2PwdrData.Export`              Writes the diffraction data or reflection list into a file
     198:meth:`~GSASIIscriptable.G2PwdrData.add_peak`            Adds a peak to the peak list. Also see :ref:`PeakRefine`.
     199:meth:`~GSASIIscriptable.G2PwdrData.set_peakFlags`       Sets refinement flags for peaks
     200:meth:`~GSASIIscriptable.G2PwdrData.refine_peaks`        Starts a peak/background fitting cycle, returns refinement results
     201:attr:`~GSASIIscriptable.G2PwdrData.Peaks`               Provides access to the peak list data structure
     202:attr:`~GSASIIscriptable.G2PwdrData.PeakList`            Provides the peak list parameter values
     203:meth:`~GSASIIscriptable.G2PwdrData.Export_peaks`        Writes the peak parameters to a text file
     204:meth:`~GSASIIscriptable.G2PwdrData.set_background`      Sets a background histogram that will be subtracted (point by point) from the current histogram.
     205=======================================================  ===============================================================================================================
     206
     207Class :class:`~GSASIIscriptable.G2Image`
     208-----------------------------------------
     209
     210  When working with images, there will be a :class:`~GSASIIscriptable.G2Image` object for each image (also see :meth:`~GSASIIscriptable.G2Project.add_image`  and :meth:`~GSASIIscriptable.G2Project.images`).
     211
     212.. tabularcolumns:: |l|p{3.5in}|
     213
     214====================================================  ===============================================================================================================
     215method                                                Use
     216====================================================  ===============================================================================================================
     217:meth:`~GSASIIscriptable.G2Image.Recalibrate`         Invokes a recalibration fit starting from the current Image Controls calibration coefficients.
     218:meth:`~GSASIIscriptable.G2Image.Integrate`           Invokes an image integration All parameters Image Controls will have previously been set.
     219:meth:`~GSASIIscriptable.G2Image.GeneratePixelMask`   Searches for "bad" pixels creating a pixel mask.
     220:meth:`~GSASIIscriptable.G2Image.setControl`          Set an Image Controls parameter in the current image.
     221:meth:`~GSASIIscriptable.G2Image.getControl`          Return an Image Controls parameter in the current image.
     222:meth:`~GSASIIscriptable.G2Image.findControl`         Get the names of Image Controls parameters.
     223:meth:`~GSASIIscriptable.G2Image.loadControls`        Load controls from a .imctrl file (also see :meth:`~GSASIIscriptable.G2Image.saveControls`).
     224:meth:`~GSASIIscriptable.G2Image.loadMasks`           Load masks from a .immask file.
     225:meth:`~GSASIIscriptable.G2Image.setVary`             Set a refinement flag for Image Controls parameter in the current image.
     226                                                      (Also see :meth:`~GSASIIscriptable.G2Image.getVary`)
     227:meth:`~GSASIIscriptable.G2Image.setCalibrant`        Set a calibrant type (or show choices) for the current image.
     228:meth:`~GSASIIscriptable.G2Image.setControlFile`      Set a image to be used as a background/dark/gain map image.
     229:meth:`~GSASIIscriptable.G2Image.getControls`         Returns the Image Controls dict for the current image.
     230:meth:`~GSASIIscriptable.G2Image.setControls`         Updates the Image Controls dict for the current image with specified key/value pairs.
     231:meth:`~GSASIIscriptable.G2Image.getMasks`            Returns the Masks dict for the current image.
     232:meth:`~GSASIIscriptable.G2Image.setMasks`            Updates the Masks dict for the current image with specified key/value pairs.
     233:meth:`~GSASIIscriptable.G2Image.IntThetaAzMap`       Computes the set of 2theta-azimuth mapping matrices to integrate the current image.
     234:meth:`~GSASIIscriptable.G2Image.IntMaskMap`          Computes the masking map for the current image for integration.
     235:meth:`~GSASIIscriptable.G2Image.MaskThetaMap`        Computes the 2theta mapping matrix to determine a pixel mask.
     236:meth:`~GSASIIscriptable.G2Image.MaskFrameMask`       Computes the Frame mask needed to determine a pixel mask.
     237:meth:`~GSASIIscriptable.G2Image.TestFastPixelMask`   Returns True if fast pixel masking is available.
     238:meth:`~GSASIIscriptable.G2Image.clearImageCache`     Clears a saved image from memory, if one is present.
     239:meth:`~GSASIIscriptable.G2Image.clearPixelMask`      Clears a saved Pixel map from the project, if one is present.
     240====================================================  ===============================================================================================================
     241
     242
     243Class :class:`~GSASIIscriptable.G2PDF`
     244-----------------------------------------
     245
     246  To work with PDF entries, object :class:`~GSASIIscriptable.G2PDF`, encapsulates a PDF entry with methods:
     247
     248.. tabularcolumns:: |l|p{3.5in}|
    60249
    61250==================================================    ===============================================================================================================
    62251method                                                Use
    63252==================================================    ===============================================================================================================
    64 :func:`GenerateReflections`                            Generates a list of unique powder reflections
    65 :func:`SetPrintLevel`                                  Sets the amout of output generated when running a script
     253:meth:`~GSASIIscriptable.G2PDF.export`                                   Used to write G(r), etc. as a file
     254:meth:`~GSASIIscriptable.G2PDF.calculate`                                Computes the PDF using parameters in the object
     255:meth:`~GSASIIscriptable.G2PDF.optimize`                                 Optimizes selected PDF parameters
     256:meth:`~GSASIIscriptable.G2PDF.set_background`                           Sets the histograms used for sample background, container, etc.
     257:meth:`~GSASIIscriptable.G2PDF.set_formula`                              Sets the chemical formula for the sample
    66258==================================================    ===============================================================================================================
    67259
    68 Class :class:`G2Project`
    69 ---------------------------------
    70 
    71   All GSASIIscriptable scripts will need to create a :class:`G2Project` object
    72   either for a new GSAS-II project or to read in an existing project (.gpx) file.
    73   The most commonly used routines in this object are:
    74 
    75 .. tabularcolumns:: |l|p{3.in}|
    76 
    77 ==================================================    ===============================================================================================================
    78 method                                                Use
    79 ==================================================    ===============================================================================================================
    80 :meth:`G2Project.save`                                Writes the current project to disk.
    81 
    82 :meth:`G2Project.add_powder_histogram`                Used to read in powder diffraction data into a project file.
    83 
    84 :meth:`G2Project.add_simulated_powder_histogram`      Defines a "dummy" powder diffraction data that will be simulated after a refinement step.
    85 
    86 :meth:`G2Project.add_image`                           Reads in an image into a project.
    87 
    88 :meth:`G2Project.add_phase`                           Adds a phase to a project
    89 
    90 :meth:`G2Project.add_PDF`                             Adds a PDF entry to a project (does not compute it)
    91 
    92 :meth:`G2Project.histograms`                          Provides a list of histograms in the current project, as :class:`G2PwdrData` objects
    93 
    94 :meth:`G2Project.phases`                              Provides a list of phases defined in the current project, as :class:`G2Phase` objects
    95 
    96 :meth:`G2Project.images`                              Provides a list of images in the current project, as :class:`G2Image` objects
    97 
    98 :meth:`G2Project.pdfs`                                Provides a list of PDFs in the current project, as :class:`G2PDF` objects
    99 
    100 :meth:`G2Project.seqref`                              Returns a :class:`G2SeqRefRes` object if there are Sequential Refinement results
    101 
    102 :meth:`G2Project.do_refinements`                      This is passed a list of dictionaries, where each dict defines a refinement step.
    103                                                       Passing a list with a single empty dict initiates a refinement with the current
    104                                                       parameters and flags. A refinement dict sets up a single refinement step
    105                                                       (as described in :ref:`Project_dicts`). Also see :ref:`Refinement_recipe`.
    106 
    107 :meth:`G2Project.set_refinement`                      This is passed a single dict which is used to set parameters and flags.
    108                                                       These actions can be performed also in :meth:`G2Project.do_refinements`.
    109 :meth:`G2Project.get_Variable`                        Retrieves the value and esd for a parameter
    110 :meth:`G2Project.get_Covariance`                      Retrieves values and covariance for a set of refined parameters
    111 :meth:`G2Project.set_Controls`                        Set overall GSAS-II control settings such as number of cycles and to set up a sequential
    112                                                       fit. (Also see :meth:`G2Project.get_Controls` to read values.)
    113 :meth:`G2Project.imageMultiDistCalib`                 Performs a global calibration fit with images at multiple distance settings.
    114 :meth:`G2Project.get_Constraints`                     Retrieves :ref:`constraint definition <Constraint_definitions_table>` entries.
    115 :meth:`G2Project.add_HoldConstr`                      Adds a hold constraint on one or more variables
    116 :meth:`G2Project.add_EquivConstr`                     Adds an equivalence constraint on two or more variables
    117 :meth:`G2Project.add_EqnConstr`                       Adds an equation-type constraint on two or more variables
    118 :meth:`G2Project.add_NewVarConstr`                    Adds an new variable as a constraint on two or more variables
    119 ==================================================    ===============================================================================================================
    120 
    121 Class :class:`G2Phase`
    122 ---------------------------------
    123 
    124 
    125   Another common object in GSASIIscriptable scripts is :class:`G2Phase`, used to encapsulate each phase in a project, with commonly used methods:
     260Class :class:`~GSASIIscriptable.G2SeqRefRes`
     261-----------------------------------------------
     262
     263  To work with Sequential Refinement results, object :class:`~GSASIIscriptable.G2SeqRefRes`, encapsulates the sequential refinement table with methods:
    126264
    127265.. tabularcolumns:: |l|p{3.5in}|
    128266
    129 ==================================================    ===============================================================================================================
    130 method                                                Use
    131 ==================================================    ===============================================================================================================
    132 :meth:`G2Phase.set_refinements`                       Provides a mechanism to set values and refinement flags for the phase. See :ref:`Phase_parameters_table`
    133                                                       for more details. This information also can be supplied within a call to :meth:`G2Project.do_refinements`
    134                                                       or :meth:`G2Project.set_refinement`.
    135 :meth:`G2Phase.clear_refinements`                     Unsets refinement flags for the phase.
    136 :meth:`G2Phase.set_HAP_refinements`                   Provides a mechanism to set values and refinement flags for parameters specific to both this phase and
    137                                                       one of its histograms. See :ref:`HAP_parameters_table`. This information also can be supplied within
    138                                                       a call to :meth:`G2Project.do_refinements` or :meth:`G2Project.set_refinement`.
    139 :meth:`G2Phase.clear_HAP_refinements`                 Clears refinement flags specific to both this phase and one of its histograms.
    140 :meth:`G2Phase.getHAPvalues`                          Returns values of parameters specific to both this phase and one of its histograms.
    141 :meth:`G2Phase.copyHAPvalues`                         Copies HAP settings between from one phase/histogram and to other histograms in same phase.
    142 :meth:`G2Phase.atoms`                                 Returns a list of atoms in the phase
    143 :meth:`G2Phase.atom`                                  Returns an atom from its label
    144 :meth:`G2Phase.histograms`                            Returns a list of histograms linked to the phase
    145 :meth:`G2Phase.get_cell`                              Returns unit cell parameters (also see :meth:`G2Phase.get_cell_and_esd`)
    146 :meth:`G2Phase.export_CIF`                            Writes a CIF for the phase
    147 :meth:`G2Phase.setSampleProfile`                      Sets sample broadening parameters
    148 :meth:`G2Phase.clearDistRestraint`                    Clears any previously defined bond distance restraint(s) for the selected phase
    149 :meth:`G2Phase.addDistRestraint`                      Finds and defines new bond distance restraint(s) for the selected phase
    150 :meth:`G2Phase.setDistRestraintWeight`                Sets the weighting factor for the bond distance restraints
    151 
    152 ==================================================    ===============================================================================================================
    153 
    154 Class :class:`G2PwdrData`
    155 ---------------------------------
    156 
    157   Another common object in GSASIIscriptable scripts is :class:`G2PwdrData`, which encapsulate each powder diffraction histogram in a project, with commonly used methods:
    158 
    159 .. tabularcolumns:: |l|p{3.5in}|
    160 
    161 ==================================================    ===============================================================================================================
    162 method                                                Use
    163 ==================================================    ===============================================================================================================
    164 :meth:`G2PwdrData.set_refinements`                    Provides a mechanism to set values and refinement flags for the powder histogram. See
    165                                                       :ref:`Histogram_parameters_table` for details. 
    166 :meth:`G2PwdrData.clear_refinements`                  Unsets refinement flags for the the powder histogram.
    167 :meth:`G2PwdrData.residuals`                          Reports R-factors etc. for the the powder histogram (also see :meth:`G2PwdrData.get_wR`)
    168 :meth:`G2PwdrData.add_back_peak`                      Adds a background peak to the histogram. Also see :meth:`G2PwdrData.del_back_peak` and
    169                                                       :meth:`G2PwdrData.ref_back_peak`.
    170 :meth:`G2PwdrData.fit_fixed_points`                   Fits background to the specified fixed points.
    171 :meth:`G2PwdrData.getdata`                            Provides access to the diffraction data associated with the histogram.
    172 :meth:`G2PwdrData.reflections`                        Provides access to the reflection lists for the histogram.
    173 :meth:`G2PwdrData.Export`                             Writes the diffraction data or reflection list into a file
    174 :meth:`G2PwdrData.add_peak`                           Adds a peak to the peak list. Also see :ref:`PeakRefine`.
    175 :meth:`G2PwdrData.set_peakFlags`                      Sets refinement flags for peaks
    176 :meth:`G2PwdrData.refine_peaks`                       Starts a peak/background fitting cycle, returns refinement results
    177 :attr:`G2PwdrData.Peaks`                              Provides access to the peak list data structure
    178 :attr:`G2PwdrData.PeakList`                           Provides the peak list parameter values
    179 :meth:`G2PwdrData.Export_peaks`                       Writes the peak parameters to a text file
    180 :meth:`G2PwdrData.set_background`                     Sets a background histogram that will be subtracted (point by point) from the current histogram.
    181 ==================================================    ===============================================================================================================
    182 
    183 Class :class:`G2Image`
    184 ---------------------------------
    185 
    186   When working with images, there will be a :class:`G2Image` object for each image (also see :meth:`G2Project.add_image`  and :meth:`G2Project.images`).
    187 
    188 .. tabularcolumns:: |l|p{3.5in}|
    189 
    190 ==================================================    ===============================================================================================================
    191 method                                                Use
    192 ==================================================    ===============================================================================================================
    193 :meth:`G2Image.Recalibrate`                           Invokes a recalibration fit starting from the current Image Controls calibration coefficients.
    194 :meth:`G2Image.Integrate`                             Invokes an image integration All parameters Image Controls will have previously been set.
    195 :meth:`G2Image.setControl`                            Set an Image Controls parameter in the current image.
    196 :meth:`G2Image.getControl`                            Return an Image Controls parameter in the current image.
    197 :meth:`G2Image.findControl`                           Get the names of Image Controls parameters.
    198 :meth:`G2Image.loadControls`                          Load controls from a .imctrl file (also see :meth:`G2Image.saveControls`).
    199 :meth:`G2Image.loadMasks`                             Load masks from a .immask file.
    200 :meth:`G2Image.setVary`                               Set a refinement flag for Image Controls parameter in the current image. (Also see :meth:`G2Image.getVary`)
    201 :meth:`G2Image.setCalibrant`                          Set a calibrant type (or show choices) for the current image.
    202 :meth:`G2Image.setControlFile`                        Set a image to be used as a background/dark/gain map image.
    203 ==================================================    ===============================================================================================================
    204 
    205 
    206 Class :class:`G2PDF`
    207 ---------------------------------
    208 
    209   To work with PDF entries, object :class:`G2PDF`, encapsulates a PDF entry with methods:
    210 
    211 .. tabularcolumns:: |l|p{3.5in}|
    212 
    213 ==================================================    ===============================================================================================================
    214 method                                                Use
    215 ==================================================    ===============================================================================================================
    216 :meth:`G2PDF.export`                                   Used to write G(r), etc. as a file
    217 :meth:`G2PDF.calculate`                                Computes the PDF using parameters in the object
    218 :meth:`G2PDF.optimize`                                 Optimizes selected PDF parameters
    219 :meth:`G2PDF.set_background`                           Sets the histograms used for sample background, container, etc.
    220 :meth:`G2PDF.set_formula`                              Sets the chemical formula for the sample
    221 ==================================================    ===============================================================================================================
    222 
    223 Class :class:`G2SeqRefRes`
    224 ---------------------------------
    225 
    226   To work with Sequential Refinement results, object :class:`G2SeqRefRes`, encapsulates the sequential refinement table with methods:
    227 
    228 .. tabularcolumns:: |l|p{3.5in}|
    229 
    230 ==================================================    ===============================================================================================================
    231 method                                                Use
    232 ==================================================    ===============================================================================================================
    233 :meth:`G2SeqRefRes.histograms`                         Provides a list of histograms used in the Sequential Refinement
    234 :meth:`G2SeqRefRes.get_cell_and_esd`                   Returns cell dimensions and standard uncertainies for a phase and histogram from the Sequential Refinement
    235 :meth:`G2SeqRefRes.get_Variable`                       Retrieves the value and esd for a parameter from a particular histogram in the Sequential Refinement
    236 :meth:`G2SeqRefRes.get_Covariance`                     Retrieves values and covariance for a set of refined parameters for a particular histogram
    237 ==================================================    ===============================================================================================================
    238 
    239 Class :class:`G2AtomRecord`
    240 ---------------------------------
    241 
    242   When working with phases, :class:`G2AtomRecord` objects provide access to the contents of each atom in a phase. This provides access to "properties" that can be
     267======================================================    ===============================================================================================================
     268method                                                    Use
     269======================================================    ===============================================================================================================
     270:meth:`~GSASIIscriptable.G2SeqRefRes.histograms`           Provides a list of histograms used in the Sequential Refinement
     271:meth:`~GSASIIscriptable.G2SeqRefRes.get_cell_and_esd`     Returns cell dimensions and standard uncertainties for a phase and histogram from the Sequential Refinement
     272:meth:`~GSASIIscriptable.G2SeqRefRes.get_Variable`         Retrieves the value and esd for a parameter from a particular histogram in the Sequential Refinement
     273:meth:`~GSASIIscriptable.G2SeqRefRes.get_Covariance`       Retrieves values and covariance for a set of refined parameters for a particular histogram
     274======================================================    ===============================================================================================================
     275
     276Class :class:`~GSASIIscriptable.G2AtomRecord`
     277-----------------------------------------------
     278
     279  When working with phases, :class:`~GSASIIscriptable.G2AtomRecord` objects provide access to the contents of each atom in a phase. This provides access to "properties" that can be
    243280  used to get values of much of the atoms associated settings: label, type, refinement_flags, coordinates, occupancy, ranId, adp_flag, and uiso. In addition,
    244   refinement_flags, occupancy and uiso can be used to set values. See the :class:`G2AtomRecord` docs and source code.
     281  refinement_flags, occupancy and uiso can be used to set values. See the :class:`~GSASIIscriptable.G2AtomRecord` docs and source code.
    245282
    246283.. _Refinement_dicts:
    … …  
    258295
    259296Project-level Parameter Dict
    260 -----------------------------
     297----------------------------
    261298
    262299As noted below (:ref:`Refinement_parameters_kinds`), there are three types of refinement parameters,
    … …  
    264301but it will often be simplest to create a composite dictionary
    265302that is used at the project-level. A dict is created with keys
    266 "set" and "clear" that can be supplied to :meth:`G2Project.set_refinement`
    267 (or :meth:`G2Project.do_refinements`, see :ref:`Refinement_recipe` below) that will
     303"set" and "clear" that can be supplied to :meth:`~GSASIIscriptable.G2Project.set_refinement`
     304(or :meth:`~GSASIIscriptable.G2Project.do_refinements`, see :ref:`Refinement_recipe` below) that will
    268305determine parameter values and will determine which parameters will be refined.
    269306
    … …  
    272309
    273310Note that optionally a list of histograms and/or phases can be supplied in the call to
    274 :meth:`G2Project.set_refinement`, but if not specified, the default is to use all defined
     311:meth:`~GSASIIscriptable.G2Project.set_refinement`, but if not specified, the default is to use all defined
    275312phases and histograms.
    276313
    … …  
    289326
    290327Refinement recipe
    291 ------------------------
     328-----------------
    292329
    293330Building on the :ref:`Project_dicts`,
    294331it is possible to specify a sequence of refinement actions as a list of
    295332these dicts and supplying this list
    296 as an argument to :meth:`G2Project.do_refinements`.
     333as an argument to :meth:`~GSASIIscriptable.G2Project.do_refinements`.
    297334
    298335As an example, this code performs the same actions as in the example in the section above:
    … …  
    318355
    319356The keys defined in the following table
    320 may be used in a dict supplied to :meth:`G2Project.do_refinements`. Note that keys ``histograms``
     357may be used in a dict supplied to :meth:`~GSASIIscriptable.G2Project.do_refinements`. Note that keys ``histograms``
    321358and ``phases`` are used to limit actions to specific sets of parameters within the project.
    322359
    … …  
    355392                       The value supplied can be the object (typically a function)
    356393                       that will be called or a string that will evaluate (in the
    357                        namespace inside :meth:`G2Project.iter_refinements` where
     394                       namespace inside
     395                       :meth:`~GSASIIscriptable.G2Project.iter_refinements` where
    358396                       ``self`` references the project.)
    359397                       Nothing is called if this is not specified.
    … …  
    393431
    394432Refinement parameter types
    395 ----------------------------
     433--------------------------
    396434
    397435Note that parameters and refinement flags used in GSAS-II fall into three classes:
    … …  
    425463
    426464Specifying Refinement Parameters
    427 =================================
     465================================
    428466
    429467Refinement parameter values and flags to turn refinement on and off are specified within dictionaries,
    … …  
    437475--------------------
    438476
    439 This table describes the dictionaries supplied to :func:`G2PwdrData.set_refinements`
    440 and :func:`G2PwdrData.clear_refinements`. As an example,
     477This table describes the dictionaries supplied to :func:`~GSASIIscriptable.G2PwdrData.set_refinements`
     478and :func:`~GSASIIscriptable.G2PwdrData.clear_refinements`. As an example,
    441479
    442480.. code-block::  python
    … …  
    446484                         "Limits": [10000, 40000]})
    447485
    448 With :meth:`G2Project.do_refinements`, these parameters should be placed inside a dict with a key
     486With :meth:`~GSASIIscriptable.G2Project.do_refinements`, these parameters should be placed inside a dict with a key
    449487``set``, ``clear``, or ``once``. Values will be set for all histograms, unless the ``histograms``
    450488key is used to define specific histograms. As an example:
    … …  
    489527                                            Note that background peaks are not handled
    490528                                            via this; see
    491                                             :meth:`G2PwdrData.ref_back_peak` instead.
     529                                            :meth:`~GSASIIscriptable.G2PwdrData.ref_back_peak` instead.
    492530                                            When value is a dict,
    493531                                            supply any of the following keys:
    … …  
    507545                                            are allowed).
    508546
    509 Instrument Parameters                       As in Sample Paramters, provide as a **list** of
     547Instrument Parameters                       As in Sample Parameters, provide as a **list** of
    510548                                            subkeys to
    511549                                            set or clear, e.g. ['X', 'Y', 'Zero', 'SH/L']
    … …  
    528566----------------
    529567
    530 This table describes the dictionaries supplied to :func:`G2Phase.set_refinements`
    531 and :func:`G2Phase.clear_refinements`. With :meth:`G2Project.do_refinements`,
     568This table describes the dictionaries supplied to :func:`~GSASIIscriptable.G2Phase.set_refinements`
     569and :func:`~GSASIIscriptable.G2Phase.clear_refinements`. With :meth:`~GSASIIscriptable.G2Project.do_refinements`,
    532570these parameters should be placed inside a dict with a key
    533571``set``, ``clear``, or ``once``. Values will be set for all phases, unless the ``phases``
    … …  
    558596------------------------------
    559597
    560 This table describes the dictionaries supplied to :func:`G2Phase.set_HAP_refinements`
    561 and :func:`G2Phase.clear_HAP_refinements`. When supplied to
    562 :meth:`G2Project.do_refinements`, these parameters should be placed inside a dict with a key
     598This table describes the dictionaries supplied to :func:`~GSASIIscriptable.G2Phase.set_HAP_refinements`
     599and :func:`~GSASIIscriptable.G2Phase.clear_HAP_refinements`. When supplied to
     600:meth:`~GSASIIscriptable.G2Project.do_refinements`, these parameters should be placed inside a dict with a key
    563601``set``, ``clear``, or ``once``. Values will be set for all histograms used in each phase,
    564602unless the ``histograms`` and ``phases`` keys are used to define specific phases and histograms.
    … …  
    610648
    611649Histogram/Phase objects
    612 ------------------------
    613 Each phase and powder histogram in a :class:`G2Project` object has an associated
     650-----------------------
     651Each phase and powder histogram in a :class:`~GSASIIscriptable.G2Project` object has an associated
    614652object. Parameters within each individual object can be turned on and off by calling
    615 :meth:`G2PwdrData.set_refinements` or :meth:`G2PwdrData.clear_refinements`
     653:meth:`~GSASIIscriptable.G2PwdrData.set_refinements` or :meth:`~GSASIIscriptable.G2PwdrData.clear_refinements`
    616654for histogram parameters;
    617 :meth:`G2Phase.set_refinements` or :meth:`G2Phase.clear_refinements`
    618 for phase parameters; and :meth:`G2Phase.set_HAP_refinements` or
    619 :meth:`G2Phase.clear_HAP_refinements`. As an example, if some_histogram is a histogram object (of type :class:`G2PwdrData`), use this to set parameters in that histogram:
     655:meth:`~GSASIIscriptable.G2Phase.set_refinements` or :meth:`~GSASIIscriptable.G2Phase.clear_refinements`
     656for phase parameters; and :meth:`~GSASIIscriptable.G2Phase.set_HAP_refinements` or
     657:meth:`~GSASIIscriptable.G2Phase.clear_HAP_refinements`. As an example, if some_histogram is a histogram object (of type :class:`~GSASIIscriptable.G2PwdrData`), use this to set parameters in that histogram:
    620658
    621659.. code-block::  python
    … …  
    668706
    669707Access to other parameter settings
    670 ===================================
     708==================================
    671709
    672710There are several hundred different types of values that can be stored in a
    … …  
    676714but sometimes determining what should be set to implement a parameter
    677715change can be complex.
    678 Several routines, :meth:`G2Phase.getHAPentryList`,
    679 :meth:`G2Phase.getPhaseEntryList` and :meth:`G2PwdrData.getHistEntryList`
     716Several routines, :meth:`~GSASIIscriptable.G2Phase.getHAPentryList`,
     717:meth:`~GSASIIscriptable.G2Phase.getPhaseEntryList` and :meth:`~GSASIIscriptable.G2PwdrData.getHistEntryList`
    680718(and their related get...Value and set.Value entries),
    681719provide a mechanism to discover what the GUI is changing inside a .gpx file.
    … …  
    764802
    765803Code Examples
    766 =================================
    767 
    768 .. _PeakRefine:
    769 
     804=============
     805
     806.. _ScriptingShortcut:
     807
     808Shortcut for Scripting Access
     809-----------------------------
     810
     811As is seen in a number of the code examples, the location where GSAS-II is
     812specified in the GSAS-II script using commands such as
     813
     814.. code-block::  python
     815
     816    import sys
     817    sys.path.insert(0,'/Users/toby/software/G2/GSASII') # needed to "find" GSAS-II modules
     818    import GSASIIscriptable as G2sc
     819
     820An alternative to this is to "install" the current GSAS-II installation into the current
     821Python interpreter. Once this has been done a single time, this single command can be used to replace
     822the three commands listed above for all future uses of GSASIIscripting:
     823
     824.. code-block::  python
     825
     826    import G2script as G2sc
     827
     828There are two ways this installation can be done. The most easy way is to invoke the
     829"Install GSASIIscriptable shortcut" command in the GSAS-II GUI's
     830File menu. Alternatively it can be accomplished from within GSASIIscriptable
     831using these commands:
     832
     833.. code-block::  python
     834
     835    import sys
     836    sys.path.insert(0,'/Users/toby/software/G2/GSASII') # update this for your installation
     837    import GSASIIscriptable as G2sc
     838    G2sc.installScriptingShortcut()
     839
     840Note the shortcut only installs use of GSAS-II with the current Python
     841installation. If more than one Python installation will be used with GSAS-II
     842(for example because different conda environments are used), a shortcut
     843should be created from within each Python environment.
     844
     845If more than one GSAS-II installation will be used with a Python installation,
     846a shortcut can only be used with one of them.
     847
     848.. _PeakRefine: 
     849 
    770850Peak Fitting
    771 --------------------
     851------------
    772852
    773853Peak refinement is performed with routines
    774 :meth:`G2PwdrData.add_peak`, :meth:`G2PwdrData.set_peakFlags` and
    775 :meth:`G2PwdrData.refine_peaks`. Method :meth:`G2PwdrData.Export_peaks` and
    776 properties :attr:`G2PwdrData.Peaks` and :attr:`G2PwdrData.PeakList`
     854:meth:`~GSASIIscriptable.G2PwdrData.add_peak`, :meth:`~GSASIIscriptable.G2PwdrData.set_peakFlags` and
     855:meth:`~GSASIIscriptable.G2PwdrData.refine_peaks`. Method :meth:`~GSASIIscriptable.G2PwdrData.Export_peaks` and
     856properties :attr:`~GSASIIscriptable.G2PwdrData.Peaks` and :attr:`~GSASIIscriptable.G2PwdrData.PeakList`
    777857provide ways to access the results. Note that when peak parameters are
    778 refined with :meth:`~G2PwdrData.refine_peaks`, the background may also
    779 be refined. Use :meth:`G2PwdrData.set_refinements` to change background
     858refined with :meth:`~GSASIIscriptable.~G2PwdrData.refine_peaks`, the background may also
     859be refined. Use :meth:`~GSASIIscriptable.G2PwdrData.set_refinements` to change background
    780860settings and the range of data used in the fit. See below for an example
    781861peak refinement script, where the data files are taken from the
    … …  
    814894
    815895Pattern Simulation
    816 -----------------------
     896------------------
    817897
    818898This shows two examples where a structure is read from a CIF, a
    … …  
    871951
    872952Simple Refinement
    873 ----------------------
     953-----------------
    874954
    875955GSASIIscriptable can be used to setup and perform simple refinements.
    … …  
    892972
    893973Sequential Refinement
    894 ----------------------
     974---------------------
    895975
    896976GSASIIscriptable can be used to setup and perform sequential refinements. This example script
    … …  
    9371017
    9381018Image Processing
    939 ----------------------
     1019----------------
    9401020
    9411021A sample script where an image is read, assigned calibration values from a file
    … …  
    9961076
    9971077Image Calibration
    998 ----------------------
     1078-----------------
    9991079
    10001080This example performs a number of cycles of constrained fitting.
    10011081A project is created with the images found in a directory, setting initial
    10021082parameters as the images are read. The initial values
    1003 for the calibration are not very good, so a :meth:`G2Image.Recalibrate` is done
     1083for the calibration are not very good, so a :meth:`~GSASIIscriptable.G2Image.Recalibrate` is done
    10041084to quickly improve the fit. Once that is done, a fit of all images is performed
    10051085where the wavelength, an offset and detector orientation are constrained to
    … …  
    10591139    gpx.save()
    10601140
     1141.. _OptInteg_Example:
     1142
     1143Optimized Image Integration
     1144---------------------------
     1145
     1146This example shows how image integration, including pixel masking of outliers,
     1147can be accomplished for a series of images where the calibration and
     1148other masking (Frame, Spots, etc) are the same for all images. This code has been optimized
     1149significantly so that computations are cached and are not repeated where possible. For one
     1150set of test data, processing of the first image takes ~5 seconds, but processing of subsequent
     1151takes on the order of 0.7 sec.
     1152
     1153This code uses an ``import G2script as G2sc`` statement to access GSASIIscriptable
     1154without referencing the GSAS-II installation directory. This requires installing a reference to
     1155the GSAS-II location into the current a Python installation, which can be done from the GUI
     1156or with scripting commands, as is discussed in :ref:`ScriptingShortcut`. Here
     1157function :func:`~GSASIIscriptable.installScriptingShortcut` was used to create
     1158the :mod:`G2script` module. That code has been retained here as comments to show what was done.
     1159
     1160To simplify use of this script, it is assumed that the script will be placed in the same
     1161directory as where the data files will be collected. Other customization is done
     1162in variables at the beginning of the code. Note that the beamline where these data are collected
     1163opens the output .tif files before the data collection for that image is complete. Once the .metadata
     1164file has been created, the image may be read.
     1165
     1166Processing progresses as follows:
     1167 * Once a set of images are found, a project is created. This is never written and will be deleted after the images are processed.
     1168 * For each image file, routine :meth:`~GSASIIscriptable.G2Project.add_image` is used to add image(s) from that file to the project. The .tif format can only hold one image, but others can have more than one.
     1169 * When the first image is processed, calibration and mask info is read; a number of computations are performed and cached.
     1170 * For subsequent images cached information is used.
     1171 * Pixel masking is performed in :meth:`~GSASIIscriptable.G2Image.GeneratePixelMask` and the mask is saved into the image.
     1172 * Image integration is performed in :meth:`~GSASIIscriptable.G2Image.Integrate`.
     1173 * Note that multiple powder patterns could be created from one image, so creation of data files is done in a loop with :meth:`~GSASIIscriptable.G2PwdrData.Export`.
     1174 * To reduce memory demands, cached versions of the Pixel map and the Image are deleted and the image file is moved to a separate directory so note that it has been processed.
     1175 * The project (.gpx file) is deleted and recreated periodically so that the memory footprint for this script does not grow.
     1176   
     1177.. code-block::  python
     1178
     1179    import os,glob,time,shutil
     1180
     1181    #### Create G2script: do this once ################################################
     1182    #import sys
     1183    #sys.path.insert(0,'/Users/toby/software/G2/GSASII') # update with your install loc
     1184    #import GSASIIscriptable as G2sc
     1185    #G2sc.installScriptingShortcut()
     1186    ###################################################################################
     1187
     1188    import G2script as G2sc
     1189    G2sc.SetPrintLevel('warn')   # reduces output
     1190
     1191    cache = {}  # place to save intermediate computations
     1192    # define location & names of files
     1193    dataLoc = os.path.abspath(os.path.split(__file__)[0]) # data in location of this file
     1194    PathWrap = lambda fil: os.path.join(dataLoc,fil) # convenience function for file paths
     1195    imgctrl = PathWrap('Si_ch3_d700-00000.imctrl')
     1196    imgmask = PathWrap('Si_ch3_d700-00000.immask')
     1197    globPattern = PathWrap("*_d700-*.tif")
     1198
     1199    def wait_for_metadata(tifname):
     1200        '''A .tif file is created before it can be read. Wait for the
     1201        metadata file to be created before trying to read both.
     1202        '''
     1203        while not os.path.exists(tifname + '.metadata'):
     1204            time.sleep(0.05)
     1205
     1206    # make a subfolder to store integrated images & integrated patterns
     1207    pathImg = os.path.join(dataLoc,'img')
     1208    if not os.path.exists(pathImg): os.mkdir(pathImg)
     1209    pathxye = os.path.join(dataLoc,'xye')
     1210    if not os.path.exists(pathxye): os.mkdir(pathxye)
     1211
     1212    while True:  # Loop will never end, stop with ctrl+C
     1213        tiflist = sorted(glob.glob(globPattern),key=lambda x: os.path.getctime(x)) # get images sorted by creation time, oldest 1st
     1214        if not tiflist:
     1215            time.sleep(0.1)
     1216            continue
     1217        gpx = G2sc.G2Project(newgpx=PathWrap('integration.gpx')) # temporary use
     1218        for tifname in tiflist:
     1219            starttime = time.time()
     1220            wait_for_metadata(tifname)
     1221            for img in gpx.add_image(tifname,fmthint="TIF",cacheImage=True):  # loop unneeded for TIF (1 image/file)
     1222                if not cache: # load & compute controls & 2theta values once
     1223                    img.loadControls(imgctrl)   # set controls/calibrations/masks
     1224                    img.loadMasks(imgmask)
     1225                    cache['Image Controls'] = img.getControls() # save controls & masks contents for quick reload
     1226                    cache['Masks'] = img.getMasks()
     1227                    cache['intMaskMap'] = img.IntMaskMap() # calc mask & TA arrays to save for integrations
     1228                    cache['intTAmap'] = img.IntThetaAzMap()
     1229                    cache['FrameMask'] = img.MaskFrameMask() # calc Frame mask & T array to save for Pixel masking
     1230                    cache['maskTmap'] = img.MaskThetaMap()
     1231                else:
     1232                    img.setControls(cache['Image Controls'])
     1233                    img.setMasks(cache['Masks'],True)  # True: reset threshold masks
     1234                img.GeneratePixelMask(esdMul=3,ThetaMap=cache['maskTmap'],FrameMask=cache['FrameMask'])
     1235                for pwdr in img.Integrate(MaskMap=cache['intMaskMap'],ThetaAzimMap=cache['intTAmap']):
     1236                    pwdr.Export(os.path.join(pathxye,os.path.split(tifname)[1]),'.xye')  # '.tif in name ignored         
     1237                img.clearImageCache()  # save some space
     1238                img.clearPixelMask()
     1239            shutil.move(tifname, pathImg)       # move file after integration so that it is not searchable
     1240            shutil.move(tifname + '.metadata', pathImg)
     1241            print('*=== processing complete, time=',time.time()-starttime,'sec\n')
     1242        del gpx
     1243       
     1244   
    10611245.. _HistExport:
    10621246
    10631247Histogram Export
    1064 --------------------
     1248----------------
    10651249
    10661250This example shows how to export a series of histograms from a collection of
    … …  
    10681252matching a wildcard in the specified directory (``dataloc``). For each file
    10691253there is a loop over histograms in that project and for each histogram
    1070 :meth:`G2PwdrData.Export` is called to write out the contents of that histogram
     1254:meth:`~GSASIIscriptable.G2PwdrData.Export` is called to write out the contents of that histogram
    10711255as CSV (comma-separated variable) file that contains data positions,
    1072 observed, computed and backgroun intensities as well as weighting for each
     1256observed, computed and background intensities as well as weighting for each
    10731257point and Q. Note that for the Export call, there is more than one choice of
    10741258exporter that can write ``.csv`` extension files, so the export hint must
    … …  
    10951279
    10961280
    1097 Installation of GSASIIscriptable
    1098 =======================================
    1099 
    1100 It is assumed that most people using GSASIIscriptable will also want to use the GUI, for this the standard
    1101 `installation instructions <https://subversion.xray.aps.anl.gov/trac/pyGSAS#Installationinstructions>`_ should be followed. The GUI includes all files needed to run scriptable.
    1102 Noting that not all GSAS-II capabilities are not available
    1103 by scripting -- yet. Even if the scripting API were to be fully completed,
    1104 there will still be some things that GSAS-II does
    1105 with the GUI would be almost impossible to implement without a
    1106 interactive graphical view of the data.
    1107 
    1108 Nonetheless, there may be times where it does make sense to install GSAS-II without all of the GUI components, for example on a compute server. As `described here
    1109 <https://gsas-ii.readthedocs.io/en/latest/packages.html#scripting-requirements>`_ the minimal python requirements are only numpy and scipy. It is assumed that
    1110 anyone able to use scripting is well posed to install from the command line.
    1111 Below are example commands to install GSAS-II for use for scripting only.
    1112 
    1113 **Installing a minimal Python configuration**: Note I have chosen below
    1114 to use the free
    1115 miniconda installer from Anaconda, Inc., but there are also plenty of
    1116 other ways to install Python, Numpy and Scipy on Linux, Windows and MacOS.
    1117 For Linux a reasonable alternative is to install these packages
    1118 (and perhaps others as below) using the Linux dist (``apt-get`` etc.).
    1119 
    1120 .. code-block::  bash
    1121 
    1122     bash ~/Downloads/Miniconda3-latest-<platform>-x86_64.sh -b -p /loc/pyg2script
    1123     source /loc/pyg2script/bin/activate
    1124     conda install numpy scipy matplotlib pillow h5py hdf5 svn
    1125 
    1126 Some discussion on these commands follows:
    1127 
    1128 * the 1st command (bash) assumes that the appropriate version of Miniconda has been downloaded from https://docs.conda.io/en/latest/miniconda.html and ``/loc/pyg2script`` is where I have selected for python to be installed. You might want to use something like ``~/pyg2script``.
    1129 * the 2nd command (source) is needed to access Python with miniconda.
    1130 * the 3rd command (conda) installs all possible packages that might be used by scripting, but matplotlib, pillow, and hdf5 are not commonly needed and could be omitted. The svn package is not needed (for example on Linux) where this has been installed in another way.
    1131 
    1132 Once svn and Python has been installed and is in the path, use these commands to install GSAS-II:
    1133 
    1134 .. code-block::  bash
    1135 
    1136     svn co https://subversion.xray.aps.anl.gov/pyGSAS/trunk /loc/GSASII
    1137     python /loc/GSASII/GSASIIscriptable.py
    1138 
    1139 Notes on these commands:
    1140 
    1141 * the 1st command (svn) is used to download the GSAS-II software. ``/loc/GSASII`` is the location where I decided to install the software. You can select something different.
    1142 * the 2nd command (python) is used to invoke GSAS-II scriptable for the first time, which is needed to load the binary files from the server.
    1143 
    11441281GSASIIscriptable Command-line Interface
    11451282=======================================
    … …  
    11591296The following subcommands are defined:
    11601297
    1161         * create, see :func:`create`
    1162         * add, see :func:`add`
    1163         * dump, see :func:`dump`
    1164         * refine, see :func:`refine`
    1165         * export, :func:`export`
    1166         * browse, see :func:`IPyBrowse`
     1298        * create, see :func:`~GSASIIscriptable.create`
     1299        * add, see :func:`~GSASIIscriptable.add`
     1300        * dump, see :func:`~GSASIIscriptable.dump`
     1301        * refine, see :func:`~GSASIIscriptable.refine`
     1302        * export, :func:`~GSASIIscriptable.export`
     1303        * browse, see :func:`~GSASIIscriptable.IPyBrowse`
    11671304
    11681305Run::
    … …  
    11761313
    11771314Parameters in JSON files
    1178 -------------------------
     1315------------------------
    11791316
    11801317The refine command requires two inputs: an existing GSAS-II project (.gpx) file and
    … …  
    11991336
    12001337API: Complete Documentation
    1201 ============================================================
     1338===========================
    12021339
    12031340.. automodule:: GSASIIscriptable
Note: See TracChangeset for help on using the changeset viewer.