Changeset 3833


Ignore:
Timestamp:
Mar 2, 2019 10:11:46 AM (3 years ago)
Author:
toby
Message:

add bkg peaks to ref dict & reorg docs

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/GSASIIscriptable.py

    r3831 r3833  
    99########### SVN repository information ###################
    1010#
    11 # TODO: integrate 2d data based on a model
    12 #
    1311"""
    1412*GSASIIscriptable: Scripting Interface*
    1513=======================================
    1614
    17 Routines for reading, writing, modifying and creating GSAS-II project (.gpx) files
    18 without use of the graphical user interface (GUI). This module defines wrapper classes around
    19 many types of GSAS-II data representations, including :class:`G2Project`,
    20 :class:`G2AtomRecord`, :class:`G2PwdrData`, :class:`G2Phase` and :class:`G2Image`.
    21 They all inherit from :class:`G2ObjectWrapper`.
    22 
    23 GSASIIscriptable offers two ways to use some of GSAS-II's capabilities
    24 without use of the graphical user interface: through Python scripts that
    25 call the :ref:`API` or via shell/batch commands that use
    26 the :ref:`CommandlineInterface`, which provides access a number of features without writing
    27 Python scripts.
    28 
    29 All GSASIIscriptable scripts will need to create a :class:`G2Project` object
    30 either for a new GSAS-II project or to read in an existing project (.gpx) file. The most commonly used routines in this object are:
    31 
    32     :meth:`G2Project.add_powder_histogram`
    33        Used to read in powder diffraction data into a project file.
    34 
    35     :meth:`G2Project.add_simulated_powder_histogram`
    36        Defines a "dummy" powder diffraction data that will be simulated after a refinement step.
    37 
    38     :meth:`G2Project.add_image`
    39        Reads in an image into a project.
    40 
    41     :meth:`G2Project.add_phase`
    42        Adds a phase to a project
    43 
    44     :meth:`G2Project.histograms`
    45        Provides a list of histograms in the current project, as :class:`G2PwdrData` objects
    46 
    47     :meth:`G2Project.phases`
    48        Provides a list of phases defined in the current project, as :class:`G2Phase` objects
    49 
    50     :meth:`G2Project.images`
    51        Provides a list of images in the current project, as :class:`G2Image` objects
    52 
    53     :meth:`G2Project.save`
    54        Writes the current project to disk.
    55 
    56     :meth:`G2Project.do_refinements`
    57        This is passed a list of dictionaries, where each dict defines a refinement step.
    58        Passing a list with a single empty dict initiates a refinement with the current
    59        parameters and flags. A refinement dict sets up a single refinement step
    60        (as described in :ref:`Project_dicts`).
    61        It specifies parameter & refinement flag changes, which are usually followed by a
    62        refinement run and optionally by calls to locally-defined Python functions.
    63        The keys used in these refinement dicts are defined in the :ref:`Refinement_recipe`
    64        table, below.
    65 
    66     :meth:`G2Project.set_refinement`
    67        This is passed a single dict which is used to set parameters and flags.
    68        These actions can be performed also in :meth:`G2Project.do_refinements`.
    69 
    70 Images, powder histograms, phases and within phases, atoms, all have their own objects and provide
    71 methods for getting and changing settings associated with them. See the classes,
    72 :class:`G2PwdrData`, :class:`G2Phase` and :class:`G2Image` for more information.
     15Routines to use an increasing amount of GSAS-II's capabilities from scripts,
     16without use of the graphical user interface (GUI). GSASIIscriptable can create and access
     17GSAS-II project (.gpx) files and can directly perform image handling and refinements. 
     18The module defines wrapper classes (inheriting from :class:`G2ObjectWrapper`) for a growing number
     19of data tree items.
     20
     21GSASIIscriptable can be used in two ways. It offers a command-line mode
     22(see :ref:`CommandlineInterface`) that
     23provides access a number of features without writing Python scripts
     24via shell/batch commands. The more powerful mode of GSASIIscriptable is
     25use is through Python scripts that
     26call the module's application interface (API), see API summary that follows or the :ref:`API`
     27section.
     28
     29==================================================
     30Application Interface (API) Summary
     31==================================================
     32This section of the documentation provides an overview to API, with full documentation
     33in the :ref:`API` section. The typical API use will be with a Python script, such as this:
     34
     35.. code-block::  python
     36
     37    from __future__ import division, print_function
     38    import os,sys
     39    sys.path.insert(0,'/Users/toby/software/G2/GSASII') # needed to "find" GSAS-II modules
     40    import GSASIIscriptable as G2sc
     41    datadir = "/Users/Scratch/"
     42    gpx = G2sc.G2Project(os.path.join(datadir,'test2.gpx'))
     43    gpx.histogram(0).add_back_peak(4.5,30000,5000,0)
     44    pardict = {'set': {'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
     45                       'Background': {'type': 'chebyschev', 'refine': True,
     46                                      'peaks':[[0,True]]}}}
     47    gpx.set_refinement(pardict)
     48
     49Most functionallity is provided via the objects and methods described in this section.
     50
     51---------------------
     52:class:`G2Project`
     53---------------------
     54
     55  All GSASIIscriptable scripts will need to create a :class:`G2Project` object
     56  either for a new GSAS-II project or to read in an existing project (.gpx) file.
     57  The most commonly used routines in this object are:
     58
     59.. tabularcolumns:: |l|p{3.5in}|
     60
     61==================================================    ===============================================================================================================
     62method                                                Use
     63==================================================    ===============================================================================================================
     64:meth:`G2Project.save`                                Writes the current project to disk.
     65
     66:meth:`G2Project.add_powder_histogram`                Used to read in powder diffraction data into a project file.
     67
     68:meth:`G2Project.add_simulated_powder_histogram`      Defines a "dummy" powder diffraction data that will be simulated after a refinement step.
     69
     70:meth:`G2Project.add_image`                           Reads in an image into a project.
     71
     72:meth:`G2Project.add_phase`                           Adds a phase to a project
     73
     74:meth:`G2Project.histograms`                          Provides a list of histograms in the current project, as :class:`G2PwdrData` objects
     75
     76:meth:`G2Project.phases`                              Provides a list of phases defined in the current project, as :class:`G2Phase` objects
     77
     78:meth:`G2Project.images`                              Provides a list of images in the current project, as :class:`G2Image` objects
     79
     80:meth:`G2Project.do_refinements`                      This is passed a list of dictionaries, where each dict defines a refinement step.
     81                                                      Passing a list with a single empty dict initiates a refinement with the current
     82                                                      parameters and flags. A refinement dict sets up a single refinement step
     83                                                      (as described in :ref:`Project_dicts`). Also see :ref:`Refinement_recipe`.
     84
     85:meth:`G2Project.set_refinement`                      This is passed a single dict which is used to set parameters and flags.
     86                                                      These actions can be performed also in :meth:`G2Project.do_refinements`.
     87==================================================    ===============================================================================================================
     88
     89---------------------
     90:class:`G2Phase`
     91---------------------
     92
     93  Another common object in GSASIIscriptable scripts is :class:`G2Phase`, used to encapsulate each phase in a project, with commonly used methods:
     94
     95.. tabularcolumns:: |l|p{3.5in}|
     96
     97==================================================    ===============================================================================================================
     98method                                                Use
     99==================================================    ===============================================================================================================
     100:meth:`G2Phase.set_refinements`                       Provides a mechanism to set values and refinement flags for the phase. See the :ref:`Phase_parameters_table`
     101                                                      for more details. This information also can be supplied within a call to :meth:`G2Project.do_refinements`
     102                                                      or :meth:`G2Project.set_refinement`.
     103:meth:`G2Phase.clear_refinements`                     Unsets refinement flags for the phase.
     104:meth:`G2Phase.set_HAP_refinements`                   Provides a mechanism to set values and refinement flags for parameters specific to both this phase and
     105                                                      one of its histograms. See the :ref:`HAP_parameters_table`. This information also can be supplied within
     106                                                      a call to :meth:`G2Project.do_refinements` or :meth:`G2Project.set_refinement`.
     107:meth:`G2Phase.clear_HAP_refinements`                 Clears refinement flags specific to both this phase and one of its histograms.
     108:meth:`G2Phase.getHAPvalues`                          Returns values of parameters specific to both this phase and one of its histograms.
     109:meth:`G2Phase.atoms`                                 Returns a list of atoms in the phase
     110:meth:`G2Phase.atom`                                  Returns an atom from its label
     111:meth:`G2Phase.histograms`                            Returns a list of histograms linked to the phase
     112:meth:`G2Phase.get_cell`                              Returns unit cell parameters (also see :meth:`G2Phase.get_cell_and_esd`)
     113:meth:`G2Phase.export_CIF`                            Writes a CIF for the phase
     114==================================================    ===============================================================================================================
     115
     116---------------------
     117:class:`G2PwdrData`
     118---------------------
     119
     120  Another common object in GSASIIscriptable scripts is :class:`G2PwdrData`, which encapsulate each powder diffraction histogram in a project, with commonly used methods:
     121
     122.. tabularcolumns:: |l|p{3.5in}|
     123
     124==================================================    ===============================================================================================================
     125method                                                Use
     126==================================================    ===============================================================================================================
     127:meth:`G2PwdrData.set_refinements`                    Provides a mechanism to set values and refinement flags for the powder histogram. See the
     128                                                      :ref:`Histogram_parameters_table` for details. 
     129:meth:`G2PwdrData.clear_refinements`                  Unsets refinement flags for the the powder histogram.
     130:meth:`G2PwdrData.residuals`                          Reports R-factors etc. for the the powder histogram (also see :meth:`G2PwdrData.get_wR`
     131:meth:`G2PwdrData.add_back_peak`                      Adds a background peak to the histogram. Also see :meth:`G2PwdrData.del_back_peak` and
     132                                                      :meth:`G2PwdrData.ref_back_peak`.
     133:meth:`G2PwdrData.fit_fixed_points`                   Fits background to the specified fixed points.
     134:meth:`G2PwdrData.getdata`                            Provides access to the diffraction data associated with the histogram.
     135:meth:`G2PwdrData.Export`                             Writes the diffraction data into a file
     136==================================================    ===============================================================================================================
     137
     138---------------------
     139:class:`G2Image`
     140---------------------
     141
     142  When working with images, there will be a :class:`G2Image` object for each image (also see :meth:`G2Project.add_image`  and :meth:`G2Project.images`).
     143
     144.. tabularcolumns:: |l|p{3.5in}|
     145
     146==================================================    ===============================================================================================================
     147method                                                Use
     148==================================================    ===============================================================================================================
     149:meth:`G2Image.Recalibrate`                           Invokes a recalibration fit starting from the current Image Controls calibration coefficients.
     150:meth:`G2Image.Integrate`                             Invokes an image integration All parameters Image Controls will have previously been set.
     151:meth:`G2Image.setControl`                            Set an Image Controls parameter in the current image.
     152:meth:`G2Image.getControl`                            Return an Image Controls parameter in the current image.
     153:meth:`G2Image.findControl`                           Get the names of Image Controls parameters.
     154:meth:`G2Image.loadControls`                          Load controls from a .imctrl file (also see :meth:`G2Image.saveControls`).
     155:meth:`G2Image.loadMasks`                             Load masks from a .immask file.
     156:meth:`G2Image.setVary`                               Set a refinement flag for Image Controls parameter in the current image. (Also see :meth:`G2Image.getVary`)
     157:meth:`G2Image.setCalibrant`                          Set a calibrant type (or show choices) for the current image.
     158:meth:`G2Image.setControlFile`                        Set a image to be used as a background/dark/gain map image.
     159==================================================    ===============================================================================================================
     160
     161----------------------
     162:class:`G2AtomRecord`
     163----------------------
     164
     165  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
     166  used to get values of much of the atoms associated settings: label, type, refinement_flags, coordinates, occupancy, ranId, adp_flag, and uiso. In addition,
     167  refinement_flags, occupancy and uiso can be used to set values. See the class docs and source code.
    73168
    74169.. _Refinement_dicts:
     
    77172Refinement parameters
    78173=====================
    79 The most complex part of scripting GSAS-II refinements
    80 comes in setting up the input to control refinements. This input is
    81 described immediately below.
     174While scripts can be written that setup refinements by changing individual parameters
     175through calls to the methods associated with objects that wrap each data tree item,
     176many of these actions can be combined into fairly complex dict structures to conduct refinement
     177steps. Use of these dicts is required with the :ref:`CommandlineInterface`. This section of the
     178documentation describes these dicts.
    82179
    83180.. _Project_dicts:
     
    89186As noted below (:ref:`Refinement_parameters_kinds`), there are three types of refinement parameters,
    90187which can be accessed individually by the objects that encapsulate individual phases and histograms
    91 but it will be usually simplest to create a composite dictionary
     188but it will often be simplest to create a composite dictionary
    92189that is used at the project-level. A dict is created with keys
    93190"set" and "clear" that can be supplied to :meth:`G2Project.set_refinement`
     
    108205    pardict = {'set': { 'Limits': [0.8, 12.0],
    109206                       'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
    110                        'Background': {'type': 'chebyschev', 'refine': True}},
     207                       'Background': {'type': 'chebyschev', 'refine': True,
     208                                      'peaks':[[0,True],[1,1,1]] }},
    111209              'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
    112210    my_project.set_refinement(pardict)
     
    132230    my_project.do_refinements([pardict])
    133231
    134 However, in addition to setting a number of parameters, this example will perform a refinement as well.
    135 If more than one dict is specified in the list, as is done in this example,
    136 two refinement steps will be performed:
     232However, in addition to setting a number of parameters, this example will perform a refinement as well,
     233after setting the parameters. More than one refinement can be performed by including more
     234than one dict in the list.
     235
     236In this example, two refinement steps will be performed:
    137237
    138238.. code-block::  python
     
    142242
    143243The keys defined in the following table
    144 may be used in a dict supplied to :meth:`G2Project.do_refinements`. Note that now keys ``histograms``
     244may be used in a dict supplied to :meth:`G2Project.do_refinements`. Note that keys ``histograms``
    145245and ``phases`` are used to limit actions to specific sets of parameters within the project.
    146246
     
    208308   
    209309
    210 In this example, a separate refinement step will be performed for each dict in the list (since
    211 "skip" is not included).
     310In this example, a separate refinement step will be performed for each dict in the list. The keyword
     311"skip" can be used to specify a dict that should not include a refinement.
    212312Note that in the second from last refinement step, parameters are both set and cleared.
    213313   
     
    320420                                            be calculated. It is calculated when this key is
    321421                                            detected, regardless of calls to refine.
     422                      peaks                 Specifies a set of flags for refining
     423                                            background peaks as a nested list. There may
     424                                            be an item for each defined background peak
     425                                            (or fewer) and each item is a list with the flag
     426                                            values for pos,int,sig & gam (fewer than 4 values
     427                                            are allowed).
    322428
    323429Instrument Parameters                       As in Sample Paramters, provide as a **list** of
     
    536642
    537643============================================================
    538 GSASIIscriptable Application Layer (API)
     644API: Complete Documentation
    539645============================================================
    540646
     
    546652(method :meth:`G2Project.do_refinements`).
    547653
    548 To change settings within hitograms, images and phases, one usually needs to use
     654To change settings within histograms, images and phases, one usually needs to use
    549655methods inside :class:`G2PwdrData`, :class:`G2Image` or :class:`G2Phase`.
    550656
    551 ---------------------------------------------------------------
    552 Complete Documentation: All classes and functions
    553 ---------------------------------------------------------------
    554657"""
    555658from __future__ import division, print_function
     
    11721275def GetCorrImage(ImageReaderlist,proj,imageRef):
    11731276    '''Gets image & applies dark, background & flat background corrections.
    1174     based on :func:`GSASIIimgGUI.GetImageZ`
     1277    based on :func:`GSASIIimgGUI.GetImageZ`. Likely for internal use only.
    11751278
    11761279    :param list ImageReaderlist: list of Reader objects for images
     
    22232326    @property
    22242327    def label(self):
     2328        '''Get the associated atom's label
     2329        '''
    22252330        return self.data[self.ct-1]
    22262331
    22272332    @property
    22282333    def type(self):
     2334        '''Get the associated atom's type
     2335        '''
    22292336        return self.data[self.ct]
    22302337
    22312338    @property
    22322339    def refinement_flags(self):
     2340        '''Get or set refinement flags for the associated atom
     2341        '''
    22332342        return self.data[self.ct+1]
    22342343
     
    22432352    @property
    22442353    def coordinates(self):
     2354        '''Get the associated atom's coordinates
     2355        '''
    22452356        return tuple(self.data[self.cx:self.cx+3])
    22462357
    22472358    @property
    22482359    def occupancy(self):
     2360        '''Get or set the associated atom's occupancy fraction
     2361        '''
    22492362        return self.data[self.cx+3]
    22502363
     
    22552368    @property
    22562369    def ranId(self):
     2370        '''Get the associated atom's Random Id number
     2371        '''
    22572372        return self.data[self.cia+8]
    22582373
    22592374    @property
    22602375    def adp_flag(self):
     2376        '''Get the associated atom's iso/aniso setting, 'I' or 'A'
     2377        '''
    22612378        # Either 'I' or 'A'
    22622379        return self.data[self.cia]
     
    22642381    @property
    22652382    def uiso(self):
     2383        '''Get or set the associated atom's Uiso or Uaniso value(s)
     2384        '''
    22662385        if self.adp_flag == 'I':
    22672386            return self.data[self.cia+1]
     
    25272646
    25282647    def set_refinements(self, refs):
    2529         """Sets the refinement parameter 'key' to the specification 'value'
     2648        """Sets the histogram refinement parameter 'key' to the specification 'value'
    25302649
    25312650        :param dict refs: A dictionary of the parameters to be set. See
     
    25842703                if value.get('fit fixed points', False):
    25852704                    do_fit_fixed_points = True
     2705                if 'peaks' in value:
     2706                    for i,flags in enumerate(value['peaks']):
     2707                        self.ref_back_peak(i,flags)
    25862708
    25872709            elif key == 'Instrument Parameters':
     
    26282750                    if 'FixedPoints' in peaks:
    26292751                        del peaks['FixedPoints']
     2752                if 'peaks' in value:
     2753                    for i in range(len(self.Background[1]['peaksList'])):
     2754                        self.ref_back_peak(i,[])
    26302755            elif key == 'Instrument Parameters':
    26312756                instrument, secondary = self.data['Instrument Parameters']
     
    33643489
    33653490        :param str calib: specifies a calibrant name which must be one of
    3366           the entries in file ImageCalibrants.py. This is validated.
     3491          the entries in file ImageCalibrants.py. This is validated and
     3492          an error provides a list of valid choices.
    33673493        '''
    33683494        import ImageCalibrants as calFile
Note: See TracChangeset for help on using the changeset viewer.