# Changeset b31b7e2 in sasview for src/sas/qtgui/Perspectives/Fitting/media/fitting_help.rst

Ignore:
Timestamp:
May 14, 2018 9:30:36 AM (4 years ago)
Branches:
ESS_GUI, ESS_GUI_batch_fitting, ESS_GUI_bumps_abstraction, ESS_GUI_iss1116, ESS_GUI_iss879, ESS_GUI_iss959, ESS_GUI_opencl, ESS_GUI_ordering, ESS_GUI_sync_sascalc
Children:
f9214aa
Parents:
d1fa2b8
Message:

Fitting perspective documentation - part 1. SASVIEW-917

File:
1 edited

### Legend:

Unmodified
 r417c03f Use the *Category* drop-down menu to chose a category of model, then select a model from the drop-down menu beneath. A graph of the chosen model, calculated using default parameter values, will appear. The graph will update dynamically as the parameter values are changed. a model from the drop-down menu to the right. The "Show Plot" button on the bottom of the dialog will become active. If you click on it, a graph of the chosen model, calculated using default parameter values, will appear. The graph will update dynamically as the parameter values are changed. You can decide your own model categorizations using the :ref:Category_Manager. Once you have selected a model you can read its help documentation by clicking on the *Description* button to the right. Once you have selected a model you can read its help documentation by right clicking on the empty space in the parameter table. .. image:: descr_fig.png Show 1D/2D *NB: Magnetic scattering can only be fitted in SasView in 2D.* To activate 2D fitting mode, click the *Show 2D* button on the *Fit Page*. To return to 1D fitting model, click the same button (which will now say *Show 1D*). To activate 2D fitting mode, select the *2D view* checkbox on the *Fit Page*. To return to 1D fitting model, de-select the same checkbox. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ *  By copying/editing an existing model (this can include models generated by the New Plugin Model* dialog) in the :ref:Python_shell or :ref:Advanced_Plugin_Editor (suitable for all use cases) :ref:Plugin_Editor (suitable for all use cases) *  By writing a model from scratch outside of SasView (only recommended for code monkeys!) ----------------------- From the *Fitting* option in the menu bar, select *Plugin Model Operations* From the *Fitting* option in the menu bar, select one of the options: .. image:: edit_model_menu.png and then one of the sub-options *  *New Plugin Model* - to create a plugin model template with a helper dialog *  *Sum|Multi(p1,p2)* - to create a plugin model by summing/multiplying *existing models* in the model library *  *Advanced Plugin Editor* - to create/edit a plugin model in a Python shell *  *Delete Plugin Models* - to delete a plugin model *  *Load Plugin Models* - to (re-)load plugin models *  *Add Custom Model* - to create a plugin model template with a helper dialog *  *Edit Custom Model* - to edit a plugin model in an editor window *  *Manage Custom Models* - to open a custom model manager allowing for a number of actions to be taken on custom models: listing, adding, deleteing, duplicating, editing *  *Add/Multiply Models* - to create a plugin model by summing/multiplying *existing models* in the model library .. _New_Plugin_Model: New Plugin Model Add Custom Model ^^^^^^^^^^^^^^^^ Relatively straightforward models can be programmed directly from the SasView GUI using the *New Plugin Model Function*. GUI using the *Plugin Definition* Function. .. image:: new_model.png A model file generated by this option can be viewed and further modified using the :ref:Advanced_Plugin_Editor . the :ref:Model_Editor. **SasView version 4.2** made it possible to specify whether a plugin created with a P(Q) model has been selected). Sum|Multi(p1,p2) ^^^^^^^^^^^^^^^^ .. Model_Editor: Model Editor ^^^^^^^^^^^^ Selecting "Edit Custom Model" option opens the editor window. .. image :: model_editor_empty.png Initially, the editor is empty. A custom model can be loaded by clicking on the *Load plugin...* button and choosing one of the existing custom plugins. Once the model is loaded, it can be edited and saved with *Save* button. Saving the model will perform the validation and only when the model is correct it will be saved to a file. Successful model check is indicated by a SasView status bar message. When *Cancel* is clicked, any changes to the model are discarded and the window is closed. For details of the SasView plugin model format see :ref:Writing_a_Plugin . To use the model, go to the relevant *Fit Page*, select the *Plugin Models* category and then select the model from the drop-down menu. .. Plugin_Manager: Plugin Manager ^^^^^^^^^^^^^^ Selecting the *Manage Custom Models* option shows a list of all the plugin models in the plugin model folder, on Windows this is *C:\\Users\\{username}\\.sasview\\plugin_models* You can add, edit, duplicate and delete these models using buttons on the right side of the list. .. image:: plugin_manager.png Add a model ^^^^^^^^^^^ Clicking the "Add" button opens the Model Editor window, allowing you to create a new plugin as described above. Duplicate a model ^^^^^^^^^^^^^^^^^ Clicking the "Duplicate" button will create a copy of the selected model(s). Naming of the duplicate follows the standard, with added * (n)* to the plugin model name, with *n* being the first unused yet integer. Edit a model ^^^^^^^^^^^^ When a single model is selected, clicking this button will open the Advanced *Model Editor* allowing you to edit the Python code of the model. If no models or multiple models are selected, the *Edit* button is disabled. Delete Plugin Models ^^^^^^^^^^^^^^^^^^^^ Simply highlight the plugin model(s) to be removed and click on the "Delete" button. The operation is final. *NB: Models shipped with SasView cannot be removed in this way.* Add/Multiply Models ^^^^^^^^^^^^^^^^^^^ .. image:: sum_model.png Plugin Model = scale_factor * (model1 * model2) + background In the *Easy Sum/Multi Editor* give the new model a function name and brief In the *Add/Multiply Models* give the new model a function name and brief description (to appear under the *Details* button on the *FitPage*). Then select two existing models, as p1 and p2, and the required operator, '+' or '*' between two existing models, as model_1 and model_2, and the required operator, '+' or '*' between them. Finally, click the *Apply* button to generate and test the model and then click *Close*. Any changes to a plugin model generated in this way only become effective *after* it is re-selected from the plugin models drop-down menu on the FitPage. If the model is not listed you can force a recompilation of the plugins by selecting *Fitting* > *Plugin Model Operations* > *Load Plugin Models*. **SasView version 4.2** introduced a much simplified and more extensible structure for plugin models generated through the Easy Sum/Multi Editor. For example, the code for a combination of a sphere model generated through the Add/Multiply Models editor. For example, the code for a combination of a sphere model with a power law model now looks like this:: that was not possible in earlier versions of SasView. .. _Advanced_Plugin_Editor: Advanced Plugin Editor ^^^^^^^^^^^^^^^^^^^^^^ Selecting this option shows all the plugin models in the plugin model folder, on Windows this is *C:\\Users\\{username}\\.sasview\\plugin_models* You can edit, modify, and save the Python code in any of these models using the *Advanced Plugin Model Editor*. Note that this is actually the same tool as the :ref:Python_shell . For details of the SasView plugin model format see :ref:Writing_a_Plugin . .. 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! When 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'. .. image:: ../calculator/new_pycrust_example_2.png To use the model, go to the relevant *Fit Page*, select the *Plugin Models* category and then select the model from the drop-down menu. Any 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. Delete Plugin Models ^^^^^^^^^^^^^^^^^^^^ Simply highlight the plugin model to be removed. The operation is final!!! *NB: Models shipped with SasView cannot be removed in this way.* Load Plugin Models ^^^^^^^^^^^^^^^^^^ This option loads (or re-loads) all models present in the *~\\.sasview\\plugin_models* folder. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ .. _Fitting_Options: Fitting Options Fit Algorithms --------------- to modify some of the configurational parameters for each optimiser. From *Fitting* in the menu bar select *Fit Options*, then select one of the following From *Fitting* in the menu bar select *Fit Algorithms*, then select one of the following optimisers: *  Nelder-Mead Simplex .. image:: fit_algorithms.png The DREAM optimiser is the most sophisticated, but may not necessarily be the best option for fitting simple models. If uncertain, try the Levenberg-Marquardt optimiser sub-region of the data for fitting. In a *FitPage* or *BatchPage* change the *Q* values in the *Min* and/or *Max* text boxes. Vertical coloured bars will appear on the graph with the data and 'theory' indicating the current *Q* limits (red = *Qmin*, purple = *Qmax*). In a *FitPage* or *BatchPage* change the tab to *Fit Options* and then change the *Q* values in the *Min* and/or *Max* text boxes. .. Vertical coloured bars will appear on the graph with the data and 'theory' indicating the current *Q* limits (red = *Qmin*, purple = *Qmax*). To return to including all data in the fit, click the *Reset* button. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ Shortcuts --------- Copy/Paste Parameters ^^^^^^^^^^^^^^^^^^^^^ It is possible to copy the parameters from one *Fit Page* and to paste them into another *Fit Page* using the same model. To *copy* parameters, either: *  Select *Edit -> Copy Params* from the menu bar, or *  Use Ctrl(Cmd on Mac) + Left Mouse Click on the *Fit Page*. To *paste* parameters, either: *  Select *Edit -> Paste Params* from the menu bar, or *  Use Ctrl(Cmd on Mac) + Shift + Left-click on the *Fit Page*. If either operation is successful a message will appear in the info line at the bottom of the SasView window. Bookmark ^^^^^^^^ To *Bookmark* a *Fit Page* either: *  Select a *Fit Page* and then click on *Bookmark* in the tool bar, or *  Right-click and select the *Bookmark* in the popup menu. .. Shortcuts --------- Copy/Paste Parameters ^^^^^^^^^^^^^^^^^^^^^ It is possible to copy the parameters from one *Fit Page* and to paste them into another *Fit Page* using the same model. To *copy* parameters, either: *  Select *Edit -> Copy Params* from the menu bar, or *  Use Ctrl(Cmd on Mac) + Left Mouse Click on the *Fit Page*. To *paste* parameters, either: *  Select *Edit -> Paste Params* from the menu bar, or *  Use Ctrl(Cmd on Mac) + Shift + Left-click on the *Fit Page*. If either operation is successful a message will appear in the info line at the bottom of the SasView window. Bookmark ^^^^^^^^ To *Bookmark* a *Fit Page* either: *  Select a *Fit Page* and then click on *Bookmark* in the tool bar, or *  Right-click and select the *Bookmark* in the popup menu. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ .. _Status_bar: Status Bar & Console -------------------- Status Bar & Log Explorer ------------------------- The status bar is located at the bottom of the SasView window and displays messages, hints, warnings and errors. At the right-hand side of the status bar is a button marked *Console*. The *Console* displays available message history and some run-time traceback information. During a long task the *Console* can also be used to monitor the progress. messages, warnings and errors. .. image:: log_explorer.png The bottom part of the SasView application window contains the *Log Explorer*. The *Log Explorer* displays available message history and run-time traceback information. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ --------------- *NB: Before proceeding, ensure that the Single Mode radio button at the bottom of* *the Data Explorer is checked (see the section* :ref:Loading_data *).* *NB: Before proceeding, ensure that the Batch mode checkbox at the bottom of* *the Data Explorer is unchecked (see the section* :ref:Loading_data *).* This mode fits one data set. When data is sent to the fitting it is plotted in a graph window as markers. .. When data is sent to the fitting it is plotted in a graph window as markers. When data is sent to the fitting, the Fit Page will show the dataset name. .. image:: dataset_name.png Clicking on the *Show Plot* will cause the data can be plotted in a graph window as markers. If a graph does not appear, or a graph window appears but is empty, then the data or in the *Console* window. Assuming the data has loaded correctly, when a model is selected a green model Assuming the data has loaded correctly, when a model is selected a blue model calculation (or what SasView calls a 'Theory') line will appear in the earlier graph window, and a second graph window will appear displaying the residuals (the *'correlated').* In the bottom left corner of the *Fit Page* is a box displaying the normalised value In the bottom right corner of the *Fit Page* is a box displaying the normalised value of the statistical $\chi^2$ parameter returned by the optimiser.