source: sasview/src/sas/sasgui/perspectives/fitting/media/fitting_help.rst @ 9258c43c

magnetic_scattrelease-4.2.2ticket-1009ticket-1094-headlessticket-1242-2d-resolutionticket-1243ticket-1249unittest-saveload
Last change on this file since 9258c43c was 9258c43c, checked in by GitHub <noreply@…>, 6 years ago

Merge pull request #151 from SasView?/ticket885b

Ticket885b

This reverts to no polydisperse parameters — ticket #885 needs to be updated to be a feature request adding polydispersity … correctly this time.

  • Property mode set to 100644
File size: 30.7 KB
RevLine 
[ec392464]1.. fitting_help.rst
2
3.. This is a port of the original SasView html help file to ReSTructured text
4.. by S King, ISIS, during SasView CodeCamp-III in Feb 2015.
5
[b64b87c]6Fitting
7=======
[ec392464]8
[3e1c9e5]9.. note:: If some code blocks are not readable, expand the documentation window
10
[a6f3613]11.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
12
13Preparing to fit data
14---------------------
15
16To fit some data you must first load some data, activate one or more data sets,
[b64b87c]17send those data sets to fitting, and select a model to fit to each data set.
[a6f3613]18
[f3377b8]19Instructions on how to load and activate data are in the section :ref:`Loading_data`.
[ec392464]20
[a6f3613]21SasView can fit data in one of three ways:
[ec392464]22
[a6f3613]23*  in *Single* fit mode - individual data sets are fitted independently one-by-one
[ec392464]24
[5295cf5]25*  in *Simultaneous* fit mode - multiple data sets are fitted simultaneously to
26   the *same* model with/without constrained parameters (this might be useful,
27   for example, if you have measured the same sample at different contrasts)
[ec392464]28
[5005ae0]29*  in *Batch* fit mode - multiple data sets are fitted sequentially to the
30   *same* model (this might be useful, for example, if you have performed
31   a kinetic or time-resolved experiment and have *lots* of data sets!)
[a6f3613]32
33.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
[ec392464]34
[a6f3613]35Selecting a model
36-----------------
[ec392464]37
[5295cf5]38The models in SasView are grouped into categories. By default these consist of:
[ec392464]39
[5295cf5]40*  *Cylinder* - cylindrical shapes (disc, right cylinder, cylinder with endcaps
41   etc)
42*  *Ellipsoid* - ellipsoidal shapes (oblate,prolate, core shell, etc)
43*  *Parellelepiped* - as the name implies
44*  *Sphere* - sheroidal shapes (sphere, core multishell, vesicle, etc)
45*  *Lamellae* - lamellar shapes (lamellar, core shell lamellar, stacked
46   lamellar, etc)
[5005ae0]47*  *Shape-Independent* - models describing structure in terms of density
48   correlation functions, fractals, peaks, power laws, etc
[5295cf5]49*  *Paracrystal* - semi ordered structures (bcc, fcc, etc)
[a6f3613]50*  *Structure Factor* - S(Q) models
[5295cf5]51*  *Plugin Models* - User-created (custom/non-library) Python models
[ec392464]52
[a6f3613]53Use the *Category* drop-down menu to chose a category of model, then select
[f3377b8]54a model from the drop-down menu beneath. A graph of the chosen model, calculated
55using default parameter values, will appear. The graph will update dynamically
56as the parameter values are changed.
57
58You can decide your own model categorizations using the :ref:`Category_Manager`.
[ce62e75]59
[a6f3613]60Once you have selected a model you can read its help documentation by clicking
61on the *Description* button to the right.
62
63Show 1D/2D
64^^^^^^^^^^
65
66Models are normally fitted to 1D (ie, I(Q) vs Q) data sets, but some models in
67SasView can also be fitted to 2D (ie, I(Qx,Qy) vs Qx vs Qy) data sets.
68
69*NB: Magnetic scattering can only be fitted in SasView in 2D.*
70
71To activate 2D fitting mode, click the *Show 2D* button on the *Fit Page*. To
72return to 1D fitting model, click the same button (which will now say *Show 1D*).
[ce62e75]73
[ec392464]74.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
75
[a6f3613]76.. _Category_Manager:
[a0637de]77
[a6f3613]78Category Manager
79----------------
80
[f3377b8]81To change the model categorizations, either choose *Category Manager* from the
82*View* option on the menubar, or click on the *Modify* button on the *Fit Page*.
[a6f3613]83
[6aad2e8]84.. image:: cat_fig0.png
[a6f3613]85
[5295cf5]86The categorization of all models except the user supplied Plugin Models can be
87reassigned, added to, and removed using *Category Manager*. Models can also be
88hidden from view in the drop-down menus.
[a6f3613]89
[6aad2e8]90.. image:: cat_fig1.png
[a6f3613]91
[f3377b8]92Changing category
93^^^^^^^^^^^^^^^^^
[a6f3613]94
[5295cf5]95To change category, highlight a model in the list by left-clicking on its entry
96and then click the *Modify* button. Use the *Change Category* panel that appears
97to make the required changes.
[a6f3613]98
[6aad2e8]99.. image:: cat_fig2.png
[a6f3613]100
[f3377b8]101To create a category for the selected model, click the *Add* button. In order
102to delete a category, select the category name and click the *Remove Selected*
103button. Then click *Done*.
[a6f3613]104
[f3377b8]105Showing/hiding models
106^^^^^^^^^^^^^^^^^^^^^
[a6f3613]107
[5295cf5]108Use the *Enable All / Disable All* buttons and the check boxes beside each model
109to select the models to show/hide. To apply the selection, click *Ok*. Otherwise
110click *Cancel*.
[a6f3613]111
[8570246]112*NB: It may be necessary to change to a different category and then back again*
[f3377b8]113*before any changes take effect.*
[a6f3613]114
115.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
116
[f3377b8]117Model Functions
118---------------
[a6f3613]119
[5295cf5]120For a complete list of all the library models available in SasView, see
121the `Model Documentation <../../../index.html>`_ .
[a6f3613]122
[f3377b8]123It is also possible to add your own models.
[a6f3613]124
[f3377b8]125.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
[a6f3613]126
[b5846a10]127.. _Adding_your_own_models:
128
[3e1c9e5]129Adding your own Models
[f3377b8]130----------------------
[a6f3613]131
[3e1c9e5]132There are essentially three ways to generate new fitting models for SasView:
133
[5295cf5]134*  Using the SasView :ref:`New_Plugin_Model` helper dialog (best for beginners
135   and/or relatively simple models)
136*  By copying/editing an existing model (this can include models generated by
[5005ae0]137   the New Plugin Model* dialog) in the :ref:`Python_shell` or
[5295cf5]138   :ref:`Advanced_Plugin_Editor` (suitable for all use cases)
139*  By writing a model from scratch outside of SasView (only recommended for code
140   monkeys!)
[3e1c9e5]141
142Please read the guidance on :ref:`Writing_a_Plugin` before proceeding.
[f3377b8]143
[3e1c9e5]144**To be found by SasView your model must reside in the *~\\.sasview\\plugin_models* folder.**
[f3377b8]145
[a6f3613]146.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
147
[3e1c9e5]148.. _Plugin_Model_Operations:
[f3377b8]149
[3e1c9e5]150Plugin Model Operations
151-----------------------
[a6f3613]152
[3e1c9e5]153From the *Fitting* option in the menu bar, select *Plugin Model Operations*
[a6f3613]154
[82b0b05e]155.. image:: edit_model_menu.png
[a6f3613]156
[3e1c9e5]157and then one of the sub-options
[f3377b8]158
[3e1c9e5]159*  *New Plugin Model* - to create a plugin model template with a helper dialog
160*  *Sum|Multi(p1,p2)* - to create a plugin model by summing/multiplying *existing models* in the model library
161*  *Advanced Plugin Editor* - to create/edit a plugin model in a Python shell
162*  *Delete Plugin Models* - to delete a plugin model
163*  *Load Plugin Models* - to (re-)load plugin models
[a6f3613]164
[3e1c9e5]165.. _New_Plugin_Model:
166
167New Plugin Model
168^^^^^^^^^^^^^^^^
[a6f3613]169
[5295cf5]170Relatively straightforward models can be programmed directly from the SasView
171GUI using the *New Plugin Model Function*.
[26c8be3]172
[6aad2e8]173.. image:: new_model.png
[a6f3613]174
[5005ae0]175When using this feature, be aware that even if your code has errors, including
176syntax errors, a model file is still generated. When you then correct the errors
177and click 'Apply' again to re-compile you will get an error informing you that
178the model already exists if the 'Overwrite' box is not checked. In this case you
179will need to supply a new model function name. By default the 'Overwrite' box is
[26c8be3]180*checked*\ .
[f3377b8]181
[26c8be3]182A model file generated by this option can be viewed and further modified using
183the :ref:`Advanced_Plugin_Editor` .
[05829fb]184
[8b89396]185Note that the New Plugin Model Feature currently does not allow for parameters
186to be polydisperse.  However they can be edited in the Advanced Editor.
187
188
189**SasView version 4.2** made it possible to specify whether a plugin created
190with the *New Plugin Model* dialog is actually a form factor P(Q) or a structure
191factor S(Q). To do this, simply add one or other of the following lines under
192the *import* statements.
[f485ba0]193
194For a form factor::
195
196     form_factor = True
[5005ae0]197
[f485ba0]198or for a structure factor::
199
200     structure_factor = True
[5005ae0]201
[8b89396]202If the plugin is a structure factor it is *also* necessary to add two variables
203to the parameter list::
[f485ba0]204
[5005ae0]205     parameters = [
[ca383a0]206                     ['radius_effective', '', 1, [0.0, numpy.inf], 'volume', ''],
207                     ['volfraction', '', 1, [0.0, 1.0], '', ''],
[e081946]208                     [...],
[f485ba0]209
210and to the declarations of the functions Iq and Iqxy:::
211
212     def Iq(x , radius_effective, volfraction, ...):
213
214     def Iqxy(x, y, radius_effective, volfraction, ...):
215
[5005ae0]216Such a plugin should then be available in the S(Q) drop-down box on a FitPage (once
[f485ba0]217a P(Q) model has been selected).
218
[a6f3613]219Sum|Multi(p1,p2)
220^^^^^^^^^^^^^^^^
221
[6aad2e8]222.. image:: sum_model.png
[a0637de]223
[5295cf5]224This option creates a custom Plugin Model of the form::
[f3377b8]225
[5295cf5]226     Plugin Model = scale_factor * {(scale_1 * model_1) +/- (scale_2 * model_2)} + background
[f3377b8]227
[3e1c9e5]228or::
229
[f485ba0]230     Plugin Model = scale_factor * (model1 * model2) + background
[3e1c9e5]231
232In the *Easy Sum/Multi Editor* give the new model a function name and brief
233description (to appear under the *Details* button on the *FitPage*). Then select
[f3377b8]234two existing models, as p1 and p2, and the required operator, '+' or '*' between
[f485ba0]235them. Finally, click the *Apply* button to generate and test the model and then click *Close*.
[f3377b8]236
[5005ae0]237Any changes to a plugin model generated in this way only become effective *after* it is re-selected
238from the plugin models drop-down menu on the FitPage. If the model is not listed you can force a
[f485ba0]239recompilation of the plugins by selecting *Fitting* > *Plugin Model Operations* > *Load Plugin Models*.
240
[5005ae0]241**SasView version 4.2** introduced a much simplified and more extensible structure for plugin models
242generated through the Easy Sum/Multi Editor. For example, the code for a combination of a sphere model
[f485ba0]243with a power law model now looks like this::
244
245     from sasmodels.core import load_model_info
246     from sasmodels.sasview_model import make_model_from_info
[5005ae0]247
[f485ba0]248     model_info = load_model_info('sphere+power_law')
[e081946]249     model_info.name = 'MyPluginModel'
[f485ba0]250     model_info.description = 'sphere + power_law'
251     Model = make_model_from_info(model_info)
252
[5005ae0]253To change the models or operators contributing to this plugin it is only necessary to edit the string
254in the brackets after *load_model_info*, though it would also be a good idea to update the model name
[f485ba0]255and description too!!!
256
[5005ae0]257The model specification string can handle multiple models and combinations of operators (+ or *) which
258are processed according to normal conventions. Thus 'model1+model2*model3' would be valid and would
259multiply model2 by model3 before adding model1. In this example, parameters in the *FitPage* would be
260prefixed A (for model2), B (for model3) and C (for model1). Whilst this might appear a little
261confusing, unless you were creating a plugin model from multiple instances of the same model the parameter
[e081946]262assignments ought to be obvious when you load the plugin.
[f485ba0]263
[5005ae0]264If you need to include another plugin model in the model specification string, just prefix the name of
[e081946]265that model with *custom*. For instance::
266
267     sphere+custom.MyPluginModel
268
269To create a P(Q)*\S(Q) model use the @ symbol instead of * like this::
270
271     sphere@hardsphere
[5005ae0]272
273This streamlined approach to building complex plugin models from existing library models, or models
274available on the *Model Marketplace*, also permits the creation of P(Q)*\S(Q) plugin models, something
275that was not possible in earlier versions of SasView.
[f3377b8]276
[3e1c9e5]277.. _Advanced_Plugin_Editor:
[f3377b8]278
[3e1c9e5]279Advanced Plugin Editor
280^^^^^^^^^^^^^^^^^^^^^^
[ec392464]281
[3e1c9e5]282Selecting this option shows all the plugin models in the plugin model folder, on Windows this is
[f3377b8]283
[afb93df]284  *C:\\Users\\{username}\\.sasview\\plugin_models*
[f3377b8]285
286You can edit, modify, and save the Python code in any of these models using the
[3e1c9e5]287*Advanced Plugin Model Editor*. Note that this is actually the same tool as the :ref:`Python_shell` .
[f3377b8]288
[afb93df]289For details of the SasView plugin model format see :ref:`Writing_a_Plugin` .
[05829fb]290
[afb93df]291.. note:: Model files generated with the Sum/Multi option are still using the SasView 3.x model format. Unless you are confident about what you are doing, it is recommended that you only modify lines denoted with the ## <----- comments!
[f3377b8]292
[3e1c9e5]293When editing is complete, select *Run* > *Check Model* from the *Advanced Plugin Model Editor* menu bar. An *Info* box will appear with the results of the compilation and model unit tests. The model will only be usable if the tests 'pass'.
[f3377b8]294
[3e1c9e5]295.. image:: ../calculator/new_pycrust_example_2.png
296
297To use the model, go to the relevant *Fit Page*, select the *Plugin Models*
[f3377b8]298category and then select the model from the drop-down menu.
299
[3e1c9e5]300Any changes to a plugin model generated in this way only become effective *after* it is re-selected from the model drop-down menu on the FitPage.
[a6f3613]301
[3e1c9e5]302Delete Plugin Models
303^^^^^^^^^^^^^^^^^^^^
[a6f3613]304
[3e1c9e5]305Simply highlight the plugin model to be removed. The operation is final!!!
[f3377b8]306
[5295cf5]307*NB: Models shipped with SasView cannot be removed in this way.*
[ec392464]308
[3e1c9e5]309Load Plugin Models
310^^^^^^^^^^^^^^^^^^
[afb93df]311
[5295cf5]312This option loads (or re-loads) all models present in the
313*~\\.sasview\\plugin_models* folder.
[afb93df]314
[ec392464]315.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
316
[4666660]317.. _Fitting_Options:
318
[f3377b8]319Fitting Options
320---------------
[a6f3613]321
[f3377b8]322It is possible to specify which optimiser SasView should use to fit the data, and
323to modify some of the configurational parameters for each optimiser.
324
325From *Fitting* in the menu bar select *Fit Options*, then select one of the following
326optimisers:
[a6f3613]327
[f3377b8]328*  DREAM
329*  Levenberg-Marquardt
330*  Quasi-Newton BFGS
331*  Differential Evolution
332*  Nelder-Mead Simplex
[a6f3613]333
[6af2785]334The DREAM optimiser is the most sophisticated, but may not necessarily be the best
335option for fitting simple models. If uncertain, try the Levenberg-Marquardt optimiser
336initially.
337
[f3377b8]338These optimisers form the *Bumps* package written by P Kienzle. For more information
[4666660]339on each optimiser, see the :ref:`Fitting_Documentation`.
[a6f3613]340
[f3377b8]341.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
[a6f3613]342
[5ac0a7a]343Fitting Limits
344--------------
345
346By default, *SasView* will attempt to model fit the full range of the data; ie,
347across all *Q* values. If necessary, however, it is possible to specify only a
348sub-region of the data for fitting.
349
350In a *FitPage* or *BatchPage* change the *Q* values in the *Min* and/or *Max*
351text boxes. Vertical coloured bars will appear on the graph with the data and
352'theory' indicating the current *Q* limits (red = *Qmin*, purple = *Qmax*).
353
354To return to including all data in the fit, click the *Reset* button.
355
356.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
357
358
[f3377b8]359Shortcuts
360---------
[a6f3613]361
[f3377b8]362Copy/Paste Parameters
363^^^^^^^^^^^^^^^^^^^^^
[a6f3613]364
[f3377b8]365It is possible to copy the parameters from one *Fit Page* and to paste them into
366another *Fit Page* using the same model.
[a6f3613]367
[f3377b8]368To *copy* parameters, either:
[a6f3613]369
[f3377b8]370*  Select *Edit -> Copy Params* from the menu bar, or
371*  Use Ctrl(Cmd on Mac) + Left Mouse Click on the *Fit Page*.
[a6f3613]372
[f3377b8]373To *paste* parameters, either:
374
375*  Select *Edit -> Paste Params* from the menu bar, or
376*  Use Ctrl(Cmd on Mac) + Shift + Left-click on the *Fit Page*.
377
378If either operation is successful a message will appear in the info line at the
379bottom of the SasView window.
380
381Bookmark
382^^^^^^^^
[a6f3613]383
[1fda506]384To *Bookmark* a *Fit Page* either:
[a6f3613]385
[f3377b8]386*  Select a *Fit Page* and then click on *Bookmark* in the tool bar, or
387*  Right-click and select the *Bookmark* in the popup menu.
[a6f3613]388
389.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
390
[4666660]391.. _Status_bar:
392
[1fda506]393Status Bar & Console
394--------------------
395
396The status bar is located at the bottom of the SasView window and displays
397messages, hints, warnings and errors.
398
399At the right-hand side of the status bar is a button marked *Console*. The *Console*
400displays available message history and some run-time traceback information.
401
402During a long task the *Console* can also be used to monitor the progress.
403
404.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
405
[6af2785]406.. _Single_Fit_Mode:
407
[a6f3613]408Single Fit Mode
409---------------
[ec392464]410
[4666660]411*NB: Before proceeding, ensure that the Single Mode radio button at the bottom of*
412*the Data Explorer is checked (see the section* :ref:`Loading_data` *).*
413
[63d314b]414This mode fits one data set.
415
[b64b87c]416When data is sent to the fitting it is plotted in a graph window as markers.
[4666660]417
418If a graph does not appear, or a graph window appears but is empty, then the data
419has not loaded correctly. Check to see if there is a message in the :ref:`Status_Bar`
420or in the *Console* window.
421
422Assuming the data has loaded correctly, when a model is selected a green model
423calculation (or what SasView calls a 'Theory') line will appear in the earlier graph
424window, and a second graph window will appear displaying the residuals (the
425difference between the experimental data and the theory) at the same X-data values.
[f9250dc]426See :ref:`Assessing_Fit_Quality`.
[4666660]427
[a7c6f38]428The objective of model-fitting is to find a *physically-plausible* model, and
429set of model parameters, that generate a theory that reproduces the experimental
430data and minimizes the values of the residuals.
[4666660]431
432Change the default values of the model parameters by hand until the theory line
[a7c6f38]433starts to represent the experimental data. Then check the tick boxes alongside
[84ac3f1]434the 'background' and 'scale' parameters. Click the *Fit* button. SasView
[a7c6f38]435will optimise the values of the 'background' and 'scale' and also display the
436corresponding uncertainties on the optimised values.
[4666660]437
[a7c6f38]438.. note::
[84ac3f1]439   If the uncertainty on a fitted parameter is unrealistically large, or if it
440   displays as NaN, the model is most likely a poor representation of the data,
441   the parameter in question is highly correlated with one or more of the other
442   fitted parameters, or the model is relatively insensitive to the value of
443   that particular parameter.
[4666660]444
[47ace50]445In the bottom left corner of the *Fit Page* is a box displaying a normalised
446value of the statistical $\chi^2$ parameter (the reduced $\chi^2$,
447See :ref:`Assessing_Fit_Quality`) returned by the optimiser.
[4666660]448
449Now check the box for another model parameter and click *Fit* again. Repeat this
[84ac3f1]450process until all relevant parameters are checked and have been optimised. As
451the fit of the theory to the experimental data improves, the value of 'Reduced
452Chi2' will decrease. A good model fit should produce values of Reduced Chi2
453close to one, and certainly << 100. See :ref:`Assessing_Fit_Quality`.
[4666660]454
455SasView has a number of different optimisers (see the section :ref:`Fitting_Options`).
456The DREAM optimiser is the most sophisticated, but may not necessarily be the best
457option for fitting simple models. If uncertain, try the Levenberg-Marquardt optimiser
458initially.
[ec392464]459
460.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
461
[a6f3613]462Simultaneous Fit Mode
463---------------------
[ec392464]464
[63d314b]465*NB: Before proceeding, ensure that the Single Mode radio button at the bottom of*
466*the Data Explorer is checked (see the section* :ref:`Loading_data` *).*
[ec392464]467
[84ac3f1]468This mode is an extension of the :ref:`Single_Fit_Mode` that allows for some
469relatively extensive constraints between fitted parameters in a single *FitPage*
470or between several *FitPage*'s (eg, to constrain all fitted parameters to be the
471same in a contrast series of *FitPages* except for the solvent sld parameter,
[47ace50]472constrain the length to be twice that of the radius in a single *FitPage*,
[84ac3f1]473fix the radius of the sphere in one *FitPage* to be the same as the radius of
474the cylinder in a second *FitPage*, etc).
[63d314b]475
[b5846a10]476If the data to be fit are in multiple files, load each file, then select each file
477in the *Data Explorer*, and *Send To Fitting*. If multiple data sets are in one file,
478load that file, *Unselect All Data*, select just those data sets to be fitted, and
479*Send To Fitting*. Either way, the result should be that for *n* data sets you have
[6af2785]4802\ *n* graphs (*n* of the data and model fit, and *n* of the resulting residuals). But
[f9250dc]481it may be helpful to minimise the residuals plots for clarity. Also see
482:ref:`Assessing_Fit_Quality`.
[b5846a10]483
[5295cf5]484*NB: If you need to use a custom Plugin Model, you must ensure that model is
485available first (see* :ref:`Adding_your_own_models` *).*
[b5846a10]486
[6af2785]487Method
488^^^^^^
489
[b5846a10]490Now go to each *FitPage* in turn and:
491
492  Select the required category and model;
493
494  Unselect all the model parameters;
495
496  Enter some starting guesses for the parameters;
497
498  Enter any parameter limits (recommended);
[63d314b]499
[b5846a10]500  Select which parameters will refine (selecting all is generally a bad idea...);
[63d314b]501
[b5846a10]502When done, select *Constrained or Simultaneous Fit* under *Fitting* in the menu bar.
503
504In the *Const & Simul Fit* page that appears, select which data sets are to be
505simultaneously fitted (this will probably be all of them or you would not have loaded
506them in the first place!).
507
508To tie parameters between the data sets with constraints, check the 'yes' radio button
509next to *Add Constraint?* in the *Fit Constraints* box.
510
[84ac3f1]511To constrain all identically named parameters to fit *simultaneously* to the
512same value across all the *Fitpages* use the *Easy Setup* drop-down buttons in
513the *Const & Simul Fit* page.
[ec392464]514
[84ac3f1]515*NB: You can only constrain parameters that are set to refine.*
[b5846a10]516
[6af2785]517Constraints will generally be of the form
518
519  Mi Parameter1 = Mj.Parameter1
520
521however the text box after the '=' sign can be used to adjust this
522relationship; for example
523
524  Mi Parameter1 = scalar \* Mj.Parameter1
525
526A 'free-form' constraint box is also provided.
[b5846a10]527
528Many constraints can be entered for a single fit.
529
[84ac3f1]530When ready, click the *Fit* button on the *Const & Simul Fit* page, NOT the *Fit*
531button on the individual *FitPage*'s.
532
[b5846a10]533The results of the model-fitting will be returned to each of the individual
534*FitPage*'s.
[ec392464]535
[a7c6f38]536Note that the Reduced Chi2 value returned is the SUM of the Reduced Chi2 of
537each fit. To see the Reduced Chi2 value for a specific *FitPage*, click the
538*Compute* button at the bottom of that *FitPage* to recalculate. Note that in
[84ac3f1]539doing so the degrees of freedom will be set to Npts.
[a7c6f38]540See :ref:`Assessing_Fit_Quality`.  Moreover in the case of constraints the
[84ac3f1]541degrees of freedom are less than one might think due to those constraints.
542
[ec392464]543.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
544
[e6c74e8]545.. _Batch_Fit_Mode:
546
[a6f3613]547Batch Fit Mode
548--------------
[ec392464]549
[6af2785]550*NB: Before proceeding, ensure that the Single Mode radio button at the bottom of*
551*the Data Explorer is checked (see the section* :ref:`Loading_data` *). The Batch*
552*Mode button will be used later on!*
[63d314b]553
[6af2785]554This mode *sequentially* fits two or more data sets *to the same model*. Unlike in
555simultaneous fitting, in batch fitting it is not possible to constrain fit parameters
556between data sets.
[ec392464]557
[6af2785]558If the data to be fit are in multiple files, load each file in the *Data Explorer*.
559If multiple data sets are in one file, load just that file. *Unselect All Data*, then
560select a single initial data set to be fitted. Fit that selected data set as described
[5295cf5]561above under :ref:`Single_Fit_Mode`.
[ec392464]562
[5295cf5]563*NB: If you need to use a custom Plugin Model, you must ensure that model is
564available first (see* :ref:`Adding_your_own_models` *).*
[ec392464]565
[6af2785]566Method
567^^^^^^
[ec392464]568
[6af2785]569Now *Select All Data* in the *Data Explorer*, check the *Batch Mode* radio button
570at the bottom of that panel and *Send To Fitting*. A *BatchPage* will be created.
[ec392464]571
[6aad2e8]572.. image:: batch_button_area.png
[ec392464]573
[6af2785]574*NB: The Batch Page can also be created by checking the Batch Mode radio button*
575*and selecting New Fit Page under Fitting in the menu bar.*
[ec392464]576
[6af2785]577Using the drop-down menus in the *BatchPage*, now set up the *same* data set
578with the *same* model that you just fitted in single fit mode. A quick way to
579set the model parameter values is to just copy them from the earlier Single
580Fit. To do this, go back to the Single Fit *FitPage*, select *Copy Params*
581under *Edit* in the menu bar, then go back to the *BatchPage* and *Paste Params*.
[ec392464]582
[6af2785]583When ready, use the *Fit* button on the *BatchPage* to perform the fitting, NOT
584the *Fit* button on the individual *FitPage*'s.
[ec392464]585
[6af2785]586Unlike in single fit mode, the results of batch fits are not returned to
587the *BatchPage*. Instead, a spreadsheet-like :ref:`Grid_Window` will appear.
[ec392464]588
[6af2785]589If you want to visually check a graph of a particular fit, click on the name of
590a *Data set* in the *Grid Window* and then click the *View Fits* button. The
591data and the model fit will be displayed. If you select mutliple data sets they
592will all appear on one graph.
[ec392464]593
[6aad2e8]594.. image:: view_button.png
[ec392464]595
[6af2785]596*NB: In theory, returning to the BatchPage and changing the name of the I(Q)*
597*data source should also work, but at the moment whilst this does change the*
598*data set displayed it always superimposes the 'theory' corresponding to the*
599*starting parameters.*
[ec392464]600
[6af2785]601If you select a 'Chi2' value and click the *View Fits* button a graph of the
602residuals for that data set is displayed. Again, if you select multiple 'Chi2'
[f9250dc]603values then all the residuals data will appear on one graph. Also see
604:ref:`Assessing_Fit_Quality`.
[ec392464]605
[6af2785]606Chain Fitting
607^^^^^^^^^^^^^
[ec392464]608
[6af2785]609By default, the *same* parameter values copied from the initial single fit into
610the *BatchPage* will be used as the starting parameters for all batch fits. It
611is, however, possible to get *SasView* to use the results of a fit to a preceding
612data set as the starting parameters for the next fit in the sequence. This
613variation of batch fitting is called *Chain Fitting*, and will considerably speed
614up model-fitting if you have lots of very similar data sets where a few parameters
615are gradually changing. Do not use chain fitting on disparate data sets.
[ec392464]616
[6af2785]617To use chain fitting, select *Chain Fitting* under *Fitting* in the menu bar. It
618toggles on/off, so selecting it again will switch back to normal batch fitting.
[ec392464]619
[6af2785]620.. _Grid_Window:
[ec392464]621
[6af2785]622Grid Window
623^^^^^^^^^^^
[ec392464]624
[6af2785]625The *Grid Window* provides an easy way to view the results from batch fitting.
626It will be displayed automatically when a batch fit completes, but may be
627opened at any time by selecting *Show Grid Window* under *View* in the menu
628bar.
[ec392464]629
[6aad2e8]630.. image:: restore_batch_window.png
[ec392464]631
[6af2785]632Once a batch fit is completed, all model parameters are displayed but *not*
633their uncertainties. To view the uncertainties, click on a given column then
634go to *Edit* in the menu bar, select *Insert Column Before* and choose the
635required data from the list. An empty column can be inserted in the same way.
[ec392464]636
[6af2785]637To remove a column from the grid, click on the column header and choose
638*Remove Column* under *Edit* in the menu bar. The same functionality also
639allows you to re-order columns.
[ec392464]640
[6af2785]641*NB: You cannot insert/remove/re-order the rows in the Grid Window.*
[ec392464]642
[6af2785]643All of the above functions are also available by right-clicking on a column
644label.
[ec392464]645
[6aad2e8]646.. image:: edit_menu.png
[ec392464]647
[6af2785]648*NB: If there is an existing Grid Window and another batch fit is performed,*
649*an additional 'Table' tab will be added to the Grid Window.*
[ec392464]650
[6af2785]651The parameter values in the *currently selected* table of the *Grid Window*
652can be output to a CSV file by choosing *Save As* under *File* in the (*Grid*
653*Window*) menu bar. The default filename includes the date and time that the
654batch fit was performed.
[ec392464]655
[6af2785]656Saved CSV files can be reloaded by choosing *Open* under *File* in the *Grid*
657*Window* menu bar. The loaded parameters will appear in a new table tab.
[ec392464]658
[6aad2e8]659.. image:: file_menu.png
[ec392464]660
[6af2785]661*NB: Saving the Grid Window does not save any experimental data, residuals*
662*or actual model fits. Consequently if you reload a saved CSV file the*
663*ability to View Fits will be lost.*
[ec392464]664
[6af2785]665Parameter Plots
666^^^^^^^^^^^^^^^
[ec392464]667
[6af2785]668Any column of *numeric* parameter values can be plotted against another using
669the *Grid Window*. Simply select one column at the time and click the *Add*
670button next to the required *X/Y-axis Selection Range* text box. When both
671the X and Y axis boxes have been completed, click the *Plot* button.
[ec392464]672
[6af2785]673When the *Add* button is clicked, *SasView* also automatically completes the
674*X/Y-axis Label* text box with the heading from Row 1 of the selected table,
675but different labels and units can be entered manually.
[ec392464]676
[6aad2e8]677.. image:: plot_button.png
[ec392464]678
[6af2785]679The *X/Y-axis Selection Range* can be edited manually. The text control box
680recognises the operators +, -, \*, /, or 'pow', and allows the following
681types of expression :
[5005ae0]682
[6af2785]683  1) if an axis label range is a function of 1 or more *columns*, write
684     this type of expression
[ec392464]685
[6af2785]686     constant1 * column_name1 [minimum row index :  maximum  row index]
687     operator constant2 * column_name2 [minimum row index :  maximum  row index]
[ec392464]688
[6af2785]689     Example: radius [2 : 5] -3 * scale [2 : 5]
[ec392464]690
[6af2785]691  2) if only some *values* of a given column are needed but the range between
692     the first row and the last row used is not continuous, write this type of
693     expression
[ec392464]694
[6af2785]695     column_name1 [minimum row index1 :  maximum  row index1] , column_name1
696     [minimum row index2 :  maximum  row index2]
[ec392464]697
[6af2785]698     Example: radius [2 : 5] , radius [10 : 25]
[5005ae0]699
[9d93c37]700.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
701
702Combined Batch Fit Mode
703-----------------------
704
[e6c74e8]705The purpose of the Combined Batch Fit is to allow running two or more batch
706fits in sequence without overwriting the output table of results.  This may be
707of interest for example if one is fitting a series of data sets where there is
708a shape change occurring in the series that requires changing the model part
709way through the series; for example a sphere to rod transition.  Indeed the
710regular batch mode does not allow for multiple models and requires all the
711files in the series to be fit with single model and set of parameters.  While
712it is of course possible to just run part of the series as a batch fit using
713model one followed by running another batch fit on the rest of the series with
714model two (and/or model three etc), doing so will overwrite the table of
715outputs from the previous batch fit(s).  This may not be desirable if one is
716interested in comparing the parameters: for example the sphere radius of set
[05b0bf6]717one and the cylinder radius of set two.
[e6c74e8]718
719Method
720^^^^^^
[9d93c37]721
[e6c74e8]722In order to use the *Combined Batch Fit*, first load all the data needed as
723described in :ref:`Loading_data`. Next start up two or more *BatchPage* fits
724following the instructions in :ref:`Batch_Fit_Mode` but **DO NOT PRESS FIT**.
725At this point the *Combine Batch Fit* menu item under the *Fitting menu* should
726be active (if there is one or no *BatchPage* the menu item will be greyed out
727and inactive).  Clicking on *Combine Batch Fit* will bring up a new panel,
728similar to the *Const & Simult Fit* panel. In this case there will be a
729checkbox for each *BatchPage* instead of each *FitPage* that should be included
730in the fit.  Once all are selected, click the Fit button on
731the *BatchPage* to run each batch fit in *sequence*
[9d93c37]732
733.. image:: combine_batch_page.png
734
[e6c74e8]735The batch table will then pop up at the end as for the case of the simple Batch
736Fitting with the following caveats:
[9d93c37]737
738.. note::
739   The order matters.  The parameters in the table will be taken from the model
[e6c74e8]740   used in the first *BatchPage* of the list.  Any parameters from the
741   second and later *BatchPage* s that have the same name as a parameter in the
742   first will show up allowing for plotting of that parameter across the
743   models. The other parameters will not be available in the grid.
[9d93c37]744.. note::
745   a corralary of the above is that currently models created as a sum|multiply
746   model will not work as desired because the generated model parameters have a
747   p#_ appended to the beginning and thus radius and p1_radius will not be
748   recognized as the same parameter.
[5005ae0]749
[9d93c37]750.. image:: combine_batch_grid.png
751
[e6c74e8]752In the example shown above the data is a time series with a shifting peak.
753The first part of the series was fitted using the *broad_peak* model, while
754the rest of the data were fit using the *gaussian_peak* model. Unfortunately the
755time is not listed in the file but the file name contains the information. As
756described in :ref:`Grid_Window`, a column can be added manually, in this case
[5005ae0]757called time, and the peak position plotted against time.
[9d93c37]758
759.. image:: combine_batch_plot.png
760
[05b0bf6]761Note the discontinuity in the peak position.  This reflects the fact that the
762Gaussian fit is a rather poor model for the data and is not actually
[e6c74e8]763finding the peak.
[ec392464]764
765.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
[6af2785]766
[84ac3f1]767.*Document History*
768
769| 2017-09-10 Paul Butler
770| 2017-09-15 Steve King
771| 2018-03-05 Paul Butler
Note: See TracBrowser for help on using the repository browser.