2.4.13 nlbegin

Brief Information

Start a nonlinear curve fitting session for XY data

Additional Information

X-Function not designed for Auto GetN Dialog.

This feature is updated in 8.0 SR5. For more details, please refer to Release Notes.

Command Line Usage

nlbegin iy:=1 func:=gauss nltree:=tt; // initialize fitting the active plot using gauss model

nlbegin iy:=(1,2) func:=expgrow1 nltree:=tt;// initialize expgrow1 model to fit data with column 1 as X and column 2 as Y

X-Function Execution Options

Please refer to the page for additional option switches when accessing the x-function from script

Variables

Description

Start a nonlinear fitting session, including option settings and parameter initialization.

The nltree is a TreeNode variable, which can control many fitting settings and allows you to read fitting results such as the parameter values, standard error, etc. The following tables list the most common objects in nltree.

Details of the nltree TreeNode

This table lists properties that are independent of parameters. Many of these properties do not appear in the tree until at least one fit iteration has occurred.

Please note that when you use the objects like *.pn, *.lbn, etc., there are two ways to access the fitting parameters. One way uses the order of the parameter to access it. Another way uses the name of the parameter. For example, when two datasets are fitted with the Gauss function, there will be 8 fitting parameters: y0, xc, w, A are the parameter names for the first dataset; y0_2, xc_2, w_2, A_2 are the parameters for the second dataset. If tt is the nltree variable, both tt.p5 and tt.y0_2 will point to the parameter y0_2 of the second dataset.

*.covarn and *.corrn are used to access the covariance matrix and correlation matrix from the report of fitting results. The two parameters exist in the nltree only when fitting results contain the covariance matrix and correlation matrix in the report. Hence it's necessary to use the script

nlend 1;

to output the report. Following script can be used to access the cell of the covariance matrix.

tt.covar1[1,2]=;  //Cell of first row and second column in the covariance matrix

Example

1. Here is an example that fits the first plot in the active layer using ExpGrow1 function.

We fix the x0 and y0 values in the fitting for the first 3 iterations. The fitted data are put in the 3rd column.

fname$=system.path.program$ + "Samples\Curve Fitting\Exponential Growth.dat"; // prepare data
newbook;
impasc;
wks.addcol();
string strData$ = %(%H,$(wks.ncols)); // Remember the name of the added column
range fitx=1, fity=3;
plotxy (1,2);
nlbegin 1 ExpGrow1 tt;      // initialize fitting session for the first plot using ExpGrow1 function
tt.x0=0;tt.f_x0=1;          // first fix the x0 value at that initial date
tt.y0=0;tt.f_y0=1;          // also fix y0 
tt.A1=1;
nlfit 3;                    // do only 3 iterations
tt.f_x0=0;tt.f_y0=0;        // then relax the x0 and y0 to fit with default max iterations
nlfit;
fity=fit(fitx);             // now we can generate the fit curve
nlend;                      // all don
layer -i %(strData$);       // Include the fit in the plot
set %(strData$) -c 2;       // Set its color to red

2. Here is an example that uses nlbegin to initialze the fitting session, then uses nlpara to open a parameters dialog to edit the initial values and bounds setting etc.

Finally, nlfit is used to continue the fitting.

nlbegin iy:=2 func:=Gauss;	// make sure col(1)&col(2) contain data
nlpara;		                // this will open a dialog to monitor parameter values

// continue to run following scripts to finish the fitting
nlfit;
nlend 1;

3. Here is an example that resets the fitting function by using nlfn if user finds that the function is not suitable to the data.

nlbegin iy:=2 func:=Gauss;	// make sure col(1)&col(2) contain data
nlfn Lorentz;
nlfit;
nlend 1 1;			// output fitting report with autoupdate

4. Here is an example that fits a multiple peaks data by setting replica.

fname$=system.path.program$ + "Samples\Curve Fitting\Multiple Peaks.dat"; // prepare data
newbook;
impasc;
nlbegin (1,2) Gauss tt replica:=2;
nlfit;
nlend 1;

5. Here is an example that performs weighted fitting.

fname$=system.path.program$ + "Samples\Curve Fitting\gaussian.dat"; // prepare data
newbook;
impasc;
nlbegin (1,2,3) Gauss tt weight:=ins;	//Set col(3) as weight data and instrumental as weight method 
nlfit;
nlend 1;

6. Here is an example that accesses the covariance matrix and correlation matrix from the report of fitting results.

fname$=system.path.program$ + "Samples\Curve Fitting\Gaussian.dat";
newbook;
impasc;
nlbegin iy:=(1,2) func:=Gauss nltree:=tt;
// Output the Correlation and Covariance matrix
nlgui gg 1;
gg.Quantities.mCov = 1;
gg.Quantities.mCor = 1;
nlgui gg 0;
nlfit;
nlend 1;
tt.covar1[1,2]=;
tt.corr1[1,2]=;

7. In this example, the script should be executed as a whole. During execution, the NLFit Parameter dialog opens, giving the opportunity to edit settings. When you click OK to close the dialog box, the next script line (nlend 1 1;) is executed automatically:

fname$=system.path.program$ + "Samples\Curve Fitting\Exponential Growth.dat"; // prepare data
newbook;
impasc;
wks.addcol();
string strData$ = %(%H,$(wks.ncols)); // Remember the name of the added column
range fitx=1, fity=3;
plotxy (1,2);
nlbegin 1 ExpGrow1 tt;      // initialize fitting session for the first plot using ExpGrow1 function
tt.x0=0;tt.f_x0=1;          // first fix the x0 value at that initial date
tt.y0=0;tt.f_y0=1;          // also fix y0 
tt.A1=1;
nlpara 1;         //dialog open and could do some settings
//Execute the next line automatically when we click “OK” on the dialog.
nlend 1 1;

Related X-Functions

nlfit, nlend, nlgui, nlpara, nlfn, nlbeginr, nlbeginz, nlbeginm, nlbegino

Keywords:regression, NLFit