Changeset 6af2785 in sasview


Ignore:
Timestamp:
Jun 4, 2015 10:45:47 AM (5 years ago)
Author:
smk78
Branches:
master, ESS_GUI, ESS_GUI_Docs, 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, costrafo411, magnetic_scatt, release-4.1.1, release-4.1.2, release-4.2.2, release_4.0.1, ticket-1009, ticket-1094-headless, ticket-1242-2d-resolution, ticket-1243, ticket-1249, ticket885, unittest-saveload
Children:
be0c318
Parents:
9d5427f
Message:

Proof read. Finally! :-)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • src/sas/perspectives/fitting/media/fitting_help.rst

    rb5846a10 r6af2785  
    258258*  Nelder-Mead Simplex 
    259259 
     260The DREAM optimiser is the most sophisticated, but may not necessarily be the best 
     261option for fitting simple models. If uncertain, try the Levenberg-Marquardt optimiser 
     262initially. 
     263 
    260264These optimisers form the *Bumps* package written by P Kienzle. For more information 
    261265on each optimiser, see the :ref:`Fitting_Documentation`. 
     
    309313 
    310314.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     315 
     316.. _Single_Fit_Mode: 
    311317 
    312318Single Fit Mode 
     
    366372*the Data Explorer is checked (see the section* :ref:`Loading_data` *).* 
    367373 
    368 This mode is an extension of the :ref:`Single Fit Mode` that fits two or more data  
     374This mode is an extension of the :ref:`Single_Fit_Mode` that fits two or more data 
    369375sets *to the same model* simultaneously. If necessary it is possible to constrain  
    370376fit parameters between data sets (eg, to fix a background level, or radius, etc). 
     
    374380load that file, *Unselect All Data*, select just those data sets to be fitted, and 
    375381*Send To Fitting*. Either way, the result should be that for *n* data sets you have 
    376 2*n* graphs (*n* of the data and model fit, and *n* of the resulting residuals). But 
     3822\ *n* graphs (*n* of the data and model fit, and *n* of the resulting residuals). But 
    377383it may be helpful to minimise the residuals plots for clarity. 
    378384 
    379385*NB: If you need to use a customized model, you must ensure that model is available* 
    380386*first (see* :ref:`Adding_your_own_models` *).* 
     387 
     388Method 
     389^^^^^^ 
    381390 
    382391Now go to each *FitPage* in turn and: 
     
    413422 
    414423Note that the chi2/Npts value returned is the SUM of the chi2/Npts of each fit. To 
    415 the chi2/Npts value for a specific *FitPage*, click the *Compute* button at the 
     424see the chi2/Npts value for a specific *FitPage*, click the *Compute* button at the 
    416425bottom of that *FitPage* to recalculate. 
    417426 
     
    422431up constraints between *FitPage*'s. 
    423432 
    424 Constraints will generally be of the form Mi Parameter1 = Mj.Parameter1, however 
    425 the text box after the '=' sign can be used to adjust this relationship; for 
    426 example Mi Parameter1 = scalar*Mj.Parameter1. A 'free-form' constraint box is 
    427 also provided. 
     433Constraints will generally be of the form 
     434 
     435  Mi Parameter1 = Mj.Parameter1 
     436 
     437however the text box after the '=' sign can be used to adjust this 
     438relationship; for example 
     439 
     440  Mi Parameter1 = scalar \* Mj.Parameter1 
     441 
     442A 'free-form' constraint box is also provided. 
    428443 
    429444Many constraints can be entered for a single fit. 
     
    433448 
    434449Note that the chi2/Npts value returned is the SUM of the chi2/Npts of each fit. To 
    435 the chi2/Npts value for a specific *FitPage*, click the *Compute* button at the 
     450see the chi2/Npts value for a specific *FitPage*, click the *Compute* button at the 
    436451bottom of that *FitPage* to recalculate. 
    437452 
     
    441456-------------- 
    442457 
    443 *NB: Before proceeding, ensure that the Batch Mode radio button at the bottom of* 
    444 *the Data Explorer is checked (see the section* :ref:`Loading_data` *).* 
    445  
    446 Batch Fit 
    447 ^^^^^^^^^ 
    448  
    449 Create a *Batch Page* by selecting the *Batch* radio button on the DataExplorer 
    450 (see figure below) and for a new control page select 'New FitPage' in the  
    451 Fitting menubar. 
     458*NB: Before proceeding, ensure that the Single Mode radio button at the bottom of* 
     459*the Data Explorer is checked (see the section* :ref:`Loading_data` *). The Batch* 
     460*Mode button will be used later on!* 
     461 
     462This mode *sequentially* fits two or more data sets *to the same model*. Unlike in 
     463simultaneous fitting, in batch fitting it is not possible to constrain fit parameters 
     464between data sets. 
     465 
     466If the data to be fit are in multiple files, load each file in the *Data Explorer*. 
     467If multiple data sets are in one file, load just that file. *Unselect All Data*, then 
     468select a single initial data set to be fitted. Fit that selected data set as described 
     469above under :ref:`Single_Fit_Mode` . 
     470 
     471*NB: If you need to use a customized model, you must ensure that model is available* 
     472*first (see* :ref:`Adding_your_own_models` *).* 
     473 
     474Method 
     475^^^^^^ 
     476 
     477Now *Select All Data* in the *Data Explorer*, check the *Batch Mode* radio button 
     478at the bottom of that panel and *Send To Fitting*. A *BatchPage* will be created. 
    452479 
    453480.. image:: batch_button_area.bmp 
    454481 
    455 Figure 1: MenuBar:  
    456  
    457 Load Data to the DataExplorer if not already loaded. 
    458  
    459 Select one or more data sets by checking the check boxes, and then make sure  
    460 that "Fitting" is selected in the dropdown menu next to the "Send To" button.  
    461 Once ready, click the 'Send To' button to set data to a BatchPage. If already  
    462 an empty batch page exists, it will be set there. Otherwise it will create a  
    463 new Batch Page. Set up the model and the parameter values as same as a single  
    464 fitting (see Single Fit help). Then use 'Fit' button to 
    465 perform the fitting. 
    466  
    467 Unlike a single fit, the results of the fittings will not return to the  
    468 BatchPage'. Instead, a Grid window will be provided once the fitting is  
    469 completed. The Grid window is also accessible from the 'View' menu  
    470 (see Figure 2). 
    471  
    472 Note that only one model is used for all the data. The initial parameter  
    473 values given in the control page will be used all the data fittings. If one  
    474 wants the FitEngine to use the initial values from the results of the  
    475 previous data fitting (if any), choose the 'Chain Fitting' option in the  
    476 Fitting menubar, which will speed up the fitting especially when you have  
    477 lots of, and similar, data sets. 
    478  
    479 Batch Window 
    480 ^^^^^^^^^^^^ 
    481 Batch Window provides an easy way to view the fit results, i.e., plot data,  
    482 fits, and residuals. Batch window will be automatically shown after a batch  
    483 fit is finished. 
    484  
    485 Once closed, it can be opened anytime from the "View" menubar item (see  
    486 Figure 2). 
     482*NB: The Batch Page can also be created by checking the Batch Mode radio button* 
     483*and selecting New Fit Page under Fitting in the menu bar.* 
     484 
     485Using the drop-down menus in the *BatchPage*, now set up the *same* data set 
     486with the *same* model that you just fitted in single fit mode. A quick way to 
     487set the model parameter values is to just copy them from the earlier Single 
     488Fit. To do this, go back to the Single Fit *FitPage*, select *Copy Params* 
     489under *Edit* in the menu bar, then go back to the *BatchPage* and *Paste Params*. 
     490 
     491When ready, use the *Fit* button on the *BatchPage* to perform the fitting, NOT 
     492the *Fit* button on the individual *FitPage*'s. 
     493 
     494Unlike in single fit mode, the results of batch fits are not returned to 
     495the *BatchPage*. Instead, a spreadsheet-like :ref:`Grid_Window` will appear. 
     496 
     497If you want to visually check a graph of a particular fit, click on the name of 
     498a *Data set* in the *Grid Window* and then click the *View Fits* button. The 
     499data and the model fit will be displayed. If you select mutliple data sets they 
     500will all appear on one graph. 
     501 
     502.. image:: view_button.bmp 
     503 
     504*NB: In theory, returning to the BatchPage and changing the name of the I(Q)* 
     505*data source should also work, but at the moment whilst this does change the* 
     506*data set displayed it always superimposes the 'theory' corresponding to the* 
     507*starting parameters.* 
     508 
     509If you select a 'Chi2' value and click the *View Fits* button a graph of the 
     510residuals for that data set is displayed. Again, if you select multiple 'Chi2' 
     511values then all the residuals data will appear on one graph. 
     512 
     513Chain Fitting 
     514^^^^^^^^^^^^^ 
     515 
     516By default, the *same* parameter values copied from the initial single fit into 
     517the *BatchPage* will be used as the starting parameters for all batch fits. It 
     518is, however, possible to get *SasView* to use the results of a fit to a preceding 
     519data set as the starting parameters for the next fit in the sequence. This 
     520variation of batch fitting is called *Chain Fitting*, and will considerably speed 
     521up model-fitting if you have lots of very similar data sets where a few parameters 
     522are gradually changing. Do not use chain fitting on disparate data sets. 
     523 
     524To use chain fitting, select *Chain Fitting* under *Fitting* in the menu bar. It 
     525toggles on/off, so selecting it again will switch back to normal batch fitting. 
     526 
     527.. _Grid_Window: 
     528 
     529Grid Window 
     530^^^^^^^^^^^ 
     531 
     532The *Grid Window* provides an easy way to view the results from batch fitting. 
     533It will be displayed automatically when a batch fit completes, but may be 
     534opened at any time by selecting *Show Grid Window* under *View* in the menu 
     535bar. 
    487536 
    488537.. image:: restore_batch_window.bmp 
    489538 
    490 Figure 2: Edit Menu:  
    491  
    492 Edit Grid 
    493 ^^^^^^^^^ 
    494  
    495 Once a batch fit is completed, all fitted and fixed model parameters are  
    496 displayed to the current sheet of the batch window except the errors of the  
    497 parameters. To view the errors, click on a given column then under *Edit*   
    498 menubar item, and insert the desired parameter by selecting a menu item with  
    499 the appropriated label. Empty column can be inserted in the same way. A  
    500 column value can be customized by editing an existing empty column. 
    501  
    502 To Remove column from the grid, select it, choose edit menu, and click the  
    503 *'remove'*  menu item. Any removed column should reinserted whenever needed. 
    504  
    505 All above options are also available when right clicking on a given column  
    506 label(see Figure 3). 
    507  
    508 *Note:*  A column always needs to be selected in order to remove or insert a  
    509 column in the grid. 
     539Once a batch fit is completed, all model parameters are displayed but *not* 
     540their uncertainties. To view the uncertainties, click on a given column then 
     541go to *Edit* in the menu bar, select *Insert Column Before* and choose the 
     542required data from the list. An empty column can be inserted in the same way. 
     543 
     544To remove a column from the grid, click on the column header and choose 
     545*Remove Column* under *Edit* in the menu bar. The same functionality also 
     546allows you to re-order columns. 
     547 
     548*NB: You cannot insert/remove/re-order the rows in the Grid Window.* 
     549 
     550All of the above functions are also available by right-clicking on a column 
     551label. 
    510552 
    511553.. image:: edit_menu.bmp 
    512554 
    513 Figure 3: Edit Menu: 
    514  
    515 Save Grid 
    516 ^^^^^^^^^ 
    517 To save the current page on the batch window, select the *'File'*  menubar  
    518 item(see Figure 4), then choose the *'Save as'*  menu item to save it as a  
    519 .csv file. 
    520  
    521 *Note:* The grid doesn't save the data array, fits, and the array residuals. 
    522 As a result, the 'View (fit) Results' functionality will be lost when 
    523 reloading the saved file. 
    524  
    525 Warning! To ensure accuracy of saved fit results, it is recommended to save  
    526 the current grid before modifying it . 
    527  
    528 Open Batch Results 
    529 ^^^^^^^^^^^^^^^^^^ 
    530  
    531 Any *csv*  file can be opened in the grid by selecting the *'Open'*  under  
    532 the *'File'*  menu in the Grid Window(see Figure 4). All columns in the file  
    533 will be displayed but insertion will not available. Insertion will be  
    534 available only when at least one column will be removed from the grid. 
     555*NB: If there is an existing Grid Window and another batch fit is performed,* 
     556*an additional 'Table' tab will be added to the Grid Window.* 
     557 
     558The parameter values in the *currently selected* table of the *Grid Window* 
     559can be output to a CSV file by choosing *Save As* under *File* in the (*Grid* 
     560*Window*) menu bar. The default filename includes the date and time that the 
     561batch fit was performed. 
     562 
     563Saved CSV files can be reloaded by choosing *Open* under *File* in the *Grid* 
     564*Window* menu bar. The loaded parameters will appear in a new table tab. 
    535565 
    536566.. image:: file_menu.bmp 
    537567 
    538 Figure 4: MenuBar: 
    539  
    540 Plot 
    541 ^^^^ 
    542  
    543 To *plot*  a column versus another, select one column at the time, click the  
    544 *'Add'*  button next to the text control of X/Y -axis *Selection Range*  to  
    545 plot the value of this column on the X/Y axis. Alternatively, all available  
    546 range can be selected by clicking the column letter (eg. B). Repeat the same  
    547 procedure the next axis. Finally, click the *'Plot'*  button. When clicking  
    548 on *Add*  button, the grid will automatically fill the axis label, but  
    549 different labels and units can be entered in the correct controls before  
    550 clicking on the plot button. 
    551  
    552 *X/Y -Axis Selection Range* can be edited manually. These text controls 
    553 allow the following types of expression (operation can be + - * /, or pow) 
     568*NB: Saving the Grid Window does not save any experimental data, residuals* 
     569*or actual model fits. Consequently if you reload a saved CSV file the* 
     570*ability to View Fits will be lost.* 
     571 
     572Parameter Plots 
     573^^^^^^^^^^^^^^^ 
     574 
     575Any column of *numeric* parameter values can be plotted against another using 
     576the *Grid Window*. Simply select one column at the time and click the *Add* 
     577button next to the required *X/Y-axis Selection Range* text box. When both 
     578the X and Y axis boxes have been completed, click the *Plot* button. 
     579 
     580When the *Add* button is clicked, *SasView* also automatically completes the 
     581*X/Y-axis Label* text box with the heading from Row 1 of the selected table, 
     582but different labels and units can be entered manually. 
     583 
     584.. image:: plot_button.bmp 
     585 
     586The *X/Y-axis Selection Range* can be edited manually. The text control box 
     587recognises the operators +, -, \*, /, or 'pow', and allows the following 
     588types of expression : 
    554589  
    555 1) if the current axis label range is a function of 1 or more columns, write  
    556 this type of expression 
    557  
    558 constant1  * column_name1 [minimum row index :  maximum  row index] operator  
    559 constant2 * column_name2 [minimum row index :  maximum  row index]  
    560  
    561 Example: radius [2 : 5] -3 * scale [2 : 5]  
    562  
    563 2) if only some values of a given column are need but the range between the  
    564 first row and the last row used is not continuous, write the following  
    565 expression in the text control 
    566  
    567 column_name1 [minimum row index1 :  maximum  row index1] , column_name1  
    568 [minimum row index2 :  maximum  row index2]  
    569  
    570 Example : radius [2 : 5] , radius [10 : 25]  
    571  
    572 Note: Both text controls ( X and Y-axis Selection Ranges) need to be filled  
    573 with valid entries for plotting to work. The dY-bar is optional (see Figure 5). 
    574  
    575 .. image:: plot_button.bmp 
    576  
    577 Figure 5: Plotting 
    578  
    579 View Column/Cell(s) 
    580 ^^^^^^^^^^^^^^^^^^^ 
    581  
    582 Select 1 or more cells from the same column, click the 'View Fits' button to  
    583 display available curves.  
    584  
    585 For example, select the cells of the  'Chi2'  column, then click the  'View Fits'   
    586 button. The plots generates will represent the residuals  plots.  
    587   
    588 If you select any cells of the 'Data' column and click the 'View Fits' button.  
    589 It generates both  data and fits in the graph (see Figure 6).  
    590  
    591 Alternatively, just click the column letter (eg. B) to choose all the  
    592 available data sets, then simply click the 'View Fits' button to plot the  
    593 data and fits.  
    594  
    595 .. image:: view_button.bmp 
    596  
    597 Figure 6: View Fits 
    598  
    599 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     590  1) if an axis label range is a function of 1 or more *columns*, write 
     591     this type of expression 
     592 
     593     constant1 * column_name1 [minimum row index :  maximum  row index] 
     594     operator constant2 * column_name2 [minimum row index :  maximum  row index] 
     595 
     596     Example: radius [2 : 5] -3 * scale [2 : 5] 
     597 
     598  2) if only some *values* of a given column are needed but the range between 
     599     the first row and the last row used is not continuous, write this type of 
     600     expression 
     601 
     602     column_name1 [minimum row index1 :  maximum  row index1] , column_name1 
     603     [minimum row index2 :  maximum  row index2] 
     604 
     605     Example: radius [2 : 5] , radius [10 : 25] 
     606 
     607.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     608 
     609.. note::  This help document was last changed by Steve King, 04Jun2015 
Note: See TracChangeset for help on using the changeset viewer.