- The FitChiTool interface
- FitChiTool tutorial
- Fit setup panel
- Data menus, variable
loading, and errors unknown
- Model group and model
menus
- The guess table
- Fit button
- Fit results
- The fit and residual plots
- The results table
- The goodness-of-fit panel
- Menu items
Running FitChiTool brings up the window shown below. On the
left third of the window is the
fit
setup panel. This panel is used to import the
fitting data, choose the fitting model, and set up the fit guesses and
bounds. Below the fit panel is the
fit
button. When
the fit is set up, pressing this button performs the chi-square fit.
On the right two-thirds of the window are components
depicting the
fit results.
- Data menus, variable
loading, and errors unknown
- Model group and model
menus
- The guess table
At the top of the fit setup panel are four pop-up menus that allow the
user to choose the workspace variables to assign to the
x,
dx,
y, and
dy arrays.
When FitChiTool is started, the interface is
loaded with all numeric vectors in the base workspace. If
vectors are added to the workspace after the interface is started, the
user must press the "Load variables" button to import the new workspace
variables to the interface.
When an array is chosen from a pull-down menu, it is displayed in the
plotting menu. The plotting combinations are:
| x matrix is chosen |
y vector is chosen |
Plotted on x axis |
Plotted on y axis |
| no |
no |
nothing |
| yes |
no |
x(:,1) |
ones |
| no |
yes |
1:length(x(:,1)) |
y |
| yes |
yes |
x(:,1) |
y |
At this time, plotting is only done vs. the first column of
x.
Future versions may allow plotting vs. other columns.
The arrays must be well-formed according to the rules of the
fitChiSquare routine (see fitChiSquare help). If one or more
of the arrays is ill-formed, the plot and pop-up menus will be cleared.
To fit without using
user-supplied errors, select the "Errors unknown?"
check box. It is not necessary to select
dx or
dy arrays
when this is checked. Note that all required arrays must be
selected and well-formed before the fit button becomes enabled.
The model menus allow the user to select which modeling function will
be fit to the data. By default, models are contained in the
"defaultChiSquareModels.mat" file, typically contained in the running
directory. This file may be edited using
the
ModelEditor GUI.
Models are arranged into groups of similar models. First
choose a group from the model groups menu, then select a model within
that group in the model menu. A model description will appear
in the model description text box. Simultaneously, the
guess table will be filled with
the appropriate number of entries, based on the model chosen and the
number of columns in the x array.
The guess table allows the user to enter starting guesses for model
parameters, as well as set bounds on the parameters. In
addition, the "Unc. Fit?" column allows the user to turn uncertainty
estimation on or off for various parameters. The columns
signify:
| Column |
Significance |
| 1 |
Parameter number |
| 2 |
Lower bound |
| 3 |
Starting guess |
| 4 |
Upper bound |
| 5 |
Uncertainty est. flag |
If an invalid value is entered in the table, the cell border will turn
red. Fitting when this is the case will cause an error.
Clicking the fit button performs the fit using fitChiSquare (type "help
fitChiSquare" for more information). The results of this fit
are displayed in the
fit results
components.
The fit button is only enabled when the following conditions are met:
- A model group and model
are selected
- x and y data
are entered and well-formed
- Either:
- dx and dy data
are entered and well-formed
- The "Errors
unknown?" box is checked
During fitting, the GUI is disabled. If the user aborts the
fit (by using CTRL-C in the command window, e.g.), the GUI will remain
disabled. It is recommended that the user restart FitChiTool
in this case. If an error occurs while fitting, the fit will
abort and the error and stack trace will be displayed in a pop-up
window. FitChiTool will be enabled and useable after this.
Please note that most errors occur because of either a syntax
error in the model function used, or because the data passed to the
model does not agree with the function's expected input.
- The fit and residual plots
- The results table
- The goodness-of-fit panel
The top plot is the fit plot. The x-axis plots the first
column of
x.
The y-axis plots
y.
The blue dots
represent the input data, the error bars represent the standard
deviation calculated by fitChiSquare, and the red line represents the
least-squares fit.
The bottom plot is the residual plot. The x-axis plots the
first column of
x.
The blue dots plot the point-by-point
weighted residual; this is defined to be the quantity
The red line plots zero. The weighted residuals should be
evenly and randomly distributed about this line if the model is the
correct fitting model AND if the measurement errors are correctly
estimated. The average value of the
squared residual
should be near or equal to 1 (in the limit of large degrees of freedom).
The results table returns the best-fit parameters and their
uncertainties. The columns have the following significance:
| Column |
Significance |
| 1 |
Parameter number |
| 2 |
Lower value at delta chi2 = 1 |
| 3 |
Best fit result |
| 4 |
Upper value at delta chi2 = 1 |
| 5 |
Uncertainty est. flag |
In the case that the parameters are normally distributed AND the
measurement errors are properly estimated about their mean (in the
limit of many fits to many data sets), the delta chi2 = 1 values may be
interpreted as the 68% confidence bounds for the result.
Given
that the model is correct, the measurement errors are usually properly
estimated when the reduced chi-square (see
goodness-of-fit
panel) is near 1 (how near depends on the number of degrees of
freedom). Either Monte-Carlo simulations or investigations on
many data sets should be used to confirm that (a) the parameters are
normally distributed and (b) the measurement errors are properly
estimated.
The table is selectable but not editable.
The goodness-of-fit panel shows
goodness-of-fit indicators. The reduced
chi-square is the chi-square divided by the number of degrees of
freedom. A reduced chi-square near 1 indicates that the model agrees
with the data (assuming measurement errors were properly
estimated/measured). A reduced chi-square much larger than 1 indicates
that an inappropriate fitting model was used (or measurement errors
were underestimated). How "near" the chi-square must be to 1 depends on
the number of degrees of freedom. See for example
Mathworld's
chi-square distribution page.
The number of degrees of freedom
is the number of data minus the number
of fitted parameters. This
must be greater
than 0 for the fit to be meaningful.
The eta-square is the nonlinear fitting corollary to r-square.
In
the case of a linear fit, the eta-square is equal to the r-square.
It is defined as:
The eta-square may be interpreted as the fraction of variation in
y
that is due to the model. (The remainder being due to noise).
- File menu
- Save
- Save as
- Import data
- Save fit to workspace
- Tools
- Fit options
- Model editor
- Choose library
- Help
- Display help
"Save" and "save as" save fits to a ".mat" file. This file
may be loaded later in MATLAB. This saves a "fit" structure,
with the following fields
| Field |
Format |
Meaning |
params |
Guess-length vector |
The best-fit parameters |
dParams |
Struct with fields: |
|
|
dl |
dChi2=1 deviation from best-fit in the negative
direction |
lVal |
dChi2=1 value in the negative direction |
du |
dChi2=1 deviation from best-fit in the positive
direction |
uVal |
dChi2=1 value in the positive direction |
d |
(dl+du)/2 |
gof |
Struct with fields: |
|
|
chi2 |
Value of chi-square
at best fit |
dof |
Degrees of freedom
of fit |
eta2 |
Value of eta-square
at best fit |
stddev |
y-length
vector |
The calculated total uncertainty of each datum |
expected |
y-length
vector |
The best-fit model value of each datum |
"Import data" will, in future releases, allow the user to load data
from a ".mat" file.
"Save to workspace" saves fits to the base workspace in the same format
as the "save" command uses.
"Fit options" will, in future releases, allow the user to set all the
options available in the command-line version of fitChiSquare.
"Model editor" brings up the
ModelEditor
GUI. If changes are made to the model library, it must be
reloaded using the "Choose library" menu option before changes will be
available within FitChiTool.
"Choose library" loads a new model library into memory.
Choosing "Display help" brings up this document.
This tutorial shows the basic use of FitChiTool. It also
demonstrates some of the application's features. To run this
tutorial, follow the steps outlined below.
Basic use
1. Open the FitChiTool GUI:
FitChiTool
2. If you have not already run FitChiToolExample, enter the
following code in the workspace. This will generate some data
to fit.
x = 0:0.2:10';
dx = zeros(length(x),1);
y = 4*sin(2*x+5).*exp(-0.3*x);
y = y';
dy = 0.5;
y = y + dy*randn(length(y),1);
dy = dy*ones(length(y),1);
3. Select the data just generated in the data pull-down menus
in FitChiTool. Select x
for x data, dx for x
error, y for y data, and
dy for y error. After selecting the data, you will see the data plotted in the fit result plot.
4. The data generated was a sinusoid with an exponentially
decaying envelope, so we should select this model with which to perform
the fit. In the group menu, select "trig"; then select "sinexp" from
the model menu. After selecting the appropriate model, you should
see the model description, showing the meaning of each parameter,
appear in the model description box. You will also see the guess
entry table resize to 4 lines.
5. In this model library, the "m" in the model description refers to the
number of columns in
x. Since
x has only one column, the parameters are:
| Parameter # |
Meaning |
| 1 |
Amplitude |
| 2 |
Frequency |
| 3 |
Phase offset |
| 4 |
Exponential growth rate |
Since we know the model from which the data were generated, we can
enter good starting guesses. Enter 4 for guess one, 2 for guess
two, 5 for guess three, and -0.3 for guess four.
6. The application is now set up to perform fitting. Click
the fit button. After a few moments, the application will display
the fit results!
7. You can now save the fit using one of the save commands in the
file menu. Choose the "Save to workspace" command and click "ok".
A new variable called "fit" appears in the workspace, containing
all the results of the fit.
Code and
documentation are copyright 2006 by Nathaniel Brahms.
