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

Display
Name
Variable
Name
I/O
and
Type
Default
Value
Description
Input iy

Input

XYRange

<active>
Specify the data to be fitted
Fitting Function Name func

Input

string

<unassigned>
Specify the fitting function used to fit data
nltree

Input/Output

TreeNode

nlt
The tree that contains the information of fitting such as parameter values, standard error, etc.
Fitting Mode mode

Input

int

auto
Specify the method to treat the input data for fitting.

Option list:

  • auto:Auto
Origin automatically chooses a data mode.
  • concat:Concatenate Fit
All input datasets are concatenated and fitted as one curve.
  • global:Global Fit
All datasets are fitted globally. This mode should be used when you want to fit one model to multiple datasets with shared parameters.
  • cons:Independent Fit - Consolidated Report
All datasets are fitted independently with the results output to a consolidated report. This mode should be used when you want to fit one model to multiple datasets without shared parameters and create a consolidated report.
Number of Replicas replica

Input

int

0
Specify the number of replicas. It is used to fit multiple peaks data by replicating the function for each peak. If the function you have selected does not support replicas, this is not available.
Dialog Theme theme

Input

string

<optional>
Specify a theme. The settings saved in it will be loaded to customize the fitting.
Notation of Parameters pnotation

Input

int

para
Specify the notation of parameters in the output tree.

Option list:

  • para:ParaName
Use the parameter names as notation.
  • abbr:Abbreviation
Use the abbreviations of the parameters as notation.
  • both:Both
Use both names and abbreviations of the parameters as notation.
Parameter Initialization init

Input

int

auto
Specify the status of parameter initialization.

Option list:

  • auto:Auto
Origin automatically decides whether to enable parameter initialization according to the FDF file of the fitting function.
  • enable:Enable
Enable parameter initialization.
  • disable:Disable
Disable parameter initialization.
Weight Method weight

Input

int

-1
Specify the global weight method.

Option list:

  • -1=auto
    Weight is Instrumental if error data are co-selected.
  • 0=none: No Weights
    No weight is used.
  • 1=ins:Instrumental (=1/ei^2)
    Use instrumental weight method.
  • 2=stat:Statistical (=1/yi)
    Use statistical weight method.
How to Initialize the NLFit Object option

Input

int

0
Specify how to initialize the NLFit Object.

Option list:

  • init_all:Init All Parameters
    Initialize all parameters and then do the fitting with these parameters.
  • change_data:Only Change Data
    Keep the former settings and only change dataset, then do the fitting to the new dataset.

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

Object Name Description Access Privilege Output to Report Worksheet
nltree.pn The value of the nth parameter (Derived Parameters excluded) Read/Write Yes
nltree.fn Set the nth parameter to be Fixed (1) or allow to vary (0) Read/Write Yes
nltree.sm shared parameter. m is the number of parameters (Derived Parameters excluded). Read/Write No
nltree.en The standard error of the nth parameter Read Yes
nltree.un Upper confidence limit. Accessible when it is calculated by theme. Read Yes
nltree.ln Lower confidence limit, Accessible when it is calculated by theme. Read Yes
nltree.ubn Upper Bounds Value Read/Write Yes
nltree.lbn Lower Bounds Value Read/Write Yes
nltree.ubonn Enable (1) or Disable (0) use of nltree.ubn Read/Write No
nltree.lbonn Enable (1) or Disable (0) use of nltree.lbn. Read/Write No
nltree.ubxn The relation between the parameter and the upper bound value. 0 corresponds to "<=", non-zero value corresponds to "<". Read/Write No
nltree.lbxn The relation between the lower bound value and the parameter. 0 corresponds to "<=", non-zero value corresponds to "<". Read/Write No
nltree.dn Calculated dependency for the parameter Read Yes
nltree.nn$, nltree.namesn$ This is a string vector. It contains the formal names of all the parameters (derived parameters are excluded). Read Yes

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.

Object Name Description Access Privilege Output to Report Worksheet
nltree.adjrn Adjust R-Square value Read Yes
nltree.chisqrn Chi-Square value Read Yes
nltree.cn Confidence interval of the nth parameter. Currently not supported Read Yes
nltree.codn R-Square (COD) Read Yes
nltree.confC Confidence Level for Curves (%) Read/Write No
nltree.confP Confidence Level for Parameters (%) Read/Write No
nltree.constr$ Linear constraints to the fitting process Read/Write No
nltree.constraints Enable/disable the linear constraints Read/Write No
nltree.corn, nltree.rn R value (correlation coefficient) Read Yes
nltree.corrn Correlation matrix (Origin 8.1 SR2) Read Yes
nltree.covarn Covariance matrix (Origin 8.1 SR2) Read Yes
nltree.datan.wdata1$ Range of weight data Read Yes
nltree.datan.wmethod1$ Weight type for each dataset Read Yes
nltree.datan.x1$ Range of X. Accessible when getting results from getnlr X-Function. Read Yes
nltree.datan.y1$ Range of Y. Accessible when getting results from getnlr X-Function. Read Yes
nltree.dofn Degree of freedom Read Yes
nltree.dpn The value of the nth derived parameter Read Yes
nltree.fitstatusn$ Fit status Read Yes
nltree.func$ Fitting function name Read Yes
nltree.maxIter Maximum number of iterations Read/Write No
nltree.ndpn$ This is a string vector. It contains the names of derived parameters. Read Yes
nltree.niter Number of iterations Read Yes
nltree.probn P value. Currently not supported Read Yes
nltree.ptsn Number of points that are actually used in the fitting Read Yes
nltree.rmse Root mean square of the error or the Standard Deviation of the model Read Yes
nltree.ssrn Residual sum of square Read Yes
nltree.tolerance The tolerance value to control fitting processing Read/Write No
nltree.tn t-Test value for the nth parameter. Currently not supported Read Yes

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