NonLinCurveFit (FPScript)
Approximates a non-linear model to a data set and returns the model parameters found, the modeled data and a large number of statistical results.
Syntax
NonLinCurveFit(Model, Data, [ InitialValues ], [ Bounds ], [ WeightingMode = NLCF_WEIGHTING_DATA ], [ Variance ], [ ScalingMode = NLCF_SCALING_NONE ], [ Scaling ], [ OutputOptions = NLCF_OUTPUT_PREDICTED_VALUES ], [ Settings ], [ Algorithm = NLCF_ALGORITHM_FULLNEWTON ] [ , OptionalParameters ])
The syntax of the NonLinCurveFit function consists of the following parts:
Part |
Description |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Model |
Determines the model to be fitted to the data. The argument can either be selected from a list of predefined models or a custom model can be specified. The custom model is returned as a string or as a data series with two strings. The first string contains the FPScript code for calculating the model function. With the second string, an FPScript code is passed that analytically calculates the partial derivations of the model function for the individual parameters and is output as a list. If only one string is specified, the derivatives are approximated numerically. The parameters of a custom model with n number of parameters must be referenced in FPScript code as p[0], p[1], ..., p[n-1]. The independent variable is x. For instance, the data series {"p[0] + p[1] * x", "[1, x]"} is specified for the model "y = a + b x" for analytical calculation or the string "p[0] + p[1] * x" is specified for numeric calculation of the derivatives. Note that x is passed as a data series and not as a scalar value, which means that the model function and partial derivatives are calculated in one step for all X values. The FPScript code must be designed accordingly. Models with several dependent variables can also be defined. The model functions are then returned as a list, and derivatives are returned as a list with lists: {"[ p[0] + p[1] * x.[0], p[1] * x.[1]^2 ]", "[ [1,x.[0] ] , [0, x.[1]^2] ]"} Permitted data structures are scalar value und data series. Supported data types are 16-bit integer, 32-bit integer, 64-bit integer und string. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Data |
These are the data to which the model is to be adapted. If the model has several dependent variables, then the argument must be specified as a list with one data set per variable. Permitted data structures are data series, data matrix, signal, signal series und list. All numeric data types are permitted, except calendar time. For complex data types the absolute value is formed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
InitialValues |
The data series with the initial values for the model parameters to be determined. If you use one of the given models, you can omit the argument. In this case, model-specific initial values will be used. The number of values corresponds to the number of model parameters multiplied by the number of peaks. Permitted data structures are data series. All numeric data types are permitted. The unit of the argument is ignored. For complex data types the absolute value is formed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Bounds |
The data matrix with the bounds for the model parameters to be determined. The matrix contains per parameter one column with two bounds. If you omit the argument, model-specific bound values or no bound values will be used. You can set individual bounds to void. The bounds must lie within the range specified for the particular model. The upper bound must be greater than the lower bound. Permitted data structures are data matrix. All numeric data types are permitted. The unit of the argument is ignored. For complex data types the absolute value is formed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
WeightingMode |
Specifies how the individual data points to which the model is to be fitted are to be weighted. The default is weighting based on the data. The argument WeightingMode can have the following values:
If this argument is omitted, it will be set to the default value NLCF_WEIGHTING_DATA. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Variance |
A data series with variances of the individual data points. If you use a custom model with several dependent variables, you will need to specify a list with one data series per variable. You only have to specify the argument if you selected custom weighting. Permitted data structures are data series und list. All numeric data types are permitted. The unit of the argument is ignored. For complex data types the absolute value is formed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ScalingMode |
Specifies which scaling is to be used for the problem. (*) not used for the Levenberg-Marquardt algorithm The argument ScalingMode can have the following values:
If this argument is omitted, it will be set to the default value NLCF_SCALING_NONE. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Scaling |
A data series with one positive scaling factor per model parameter. You only need to specify the argument if you selected custom scaling. Permitted data structures are data series. All numeric data types are permitted. The unit of the argument is ignored. For complex data types the absolute value is formed. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
OutputOptions |
Specifies which results are to be returned. Several results are output as a list. If you omit the argument, all available results are output. If, for instance, the correlation matrix and the covariance matrix are to be output, the argument must contain the value NLCF_OUTPUT_CORRELATION + NLCF_OUTPUT_COVARIANCE. Statistical Output Options for Non-Linear Curve Fitting helps determine the goodness-of-fit. (m = number of data points, n = number of parameters) (*) The covariance matrix is used to calculate these statistical characteristic quantities. Calculating the covariance matrix is not possible when using the Full Newton algorithm if bounds are specified and scaling (all except NLCF_SCALING_NONE) is used. The argument OutputOptions can have the following values:
If this argument is omitted, it will be set to the default value NLCF_OUTPUT_PREDICTED_VALUES. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Settings |
A list that modifies the settings for the algorithm used. The OptionalParameters argument can have the following elements:
* only used with the Levenberg-Marquardt algorithm ** only used with the Full Newton algorithm The values are returned as a list; for instance: [<MaximumNumberOfFunctionCalls > 100, <XTolerance> 1e-015, <YTolerance> 1e-015, <FTolerance> 1e-015, <StepBound> 1e+002] Permitted data structures are list. All numeric data types are permitted. The unit of the argument is ignored. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Algorithm |
Specifies which algorithm is to be used. The argument Algorithm can have the following values:
If this argument is omitted, it will be set to the default value NLCF_ALGORITHM_FULLNEWTON. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
OptionalParameters |
A list that can be passed to the model. The OptionalParameters argument can have the following elements:
The values are returned as a list. Below is an example of a model with three parameters and twp peaks: [<NumberOfPeaks>2, <FixedParameters>{FALSE, TRUE, FALSE, FALSE, FALSE, FALSE}, <SharedParameters>{FALSE, FALSE, FALSE}] Permitted data structures are list. All data types are permitted. The unit of the argument is ignored. |
Remarks
The status output describes the reason why a calculation was aborted. A distinction is made between two groups. The algorithm ends successfully if certain convergence criteria are fulfilled. If this is not the case, the algorithm aborts the calculation based on termination criteria. The result of the function is then only the status output.
Convergence criteria:
Constant |
Meaning |
---|---|
0 |
X convergence. |
1 |
Relative function convergence. |
2 |
Absolute function convergence. |
3 |
X convergence and relative function convergence. |
4 |
Tolerance for the cosine of the angle between the columns of the current Jacobian matrix and the corresponding residual vector. |
Termination criteria:
Constant |
Meaning |
---|---|
5 |
Singular convergence. |
6 |
False convergence. |
7 |
Maximum number of iterations reached. |
8 |
Wrong initial values. |
9 |
Gradient cannot be calculated. |
10 |
Manually abort calculation. |
11 |
Internal algorithm error. |
12 |
Maximum number of function calls reached. |
You can access the results using the following list element names:
Constant |
Meaning |
---|---|
.["AverageResidual"] |
Average residual. |
.["Baseline"] |
Baseline for models with several peaks. |
.["Confidence95"] |
95% confidence band. |
.["Confidence99"] |
99% confidence band. |
.["Confidence999"] |
99.9% confidence band. |
.["ConfidenceParameter95"] |
95% confidence intervals of parameters. |
.["ConfidenceParameter99"] |
99% confidence intervals of parameters. |
.["ConfidenceParameter999"] |
99.9% confidence intervals of parameters. |
.["Correlation"] |
Correlation matrix. |
.["Covariance"] |
Covariance matrix. |
.["ErrorVariance"] |
Error variance. |
.["Iterations"] |
Number of iterations needed. |
.["ParameterError"] |
Standard error of parameters. |
.["Peaks"] |
Peak curves for models with several peaks. |
.["Prediction95"] |
95% prediction band. |
.["Prediction99"] |
99% prediction band. |
.["Prediction999"] |
99.9% prediction band. |
.["PredictedValues"] |
The data modeled. |
.["R2"] |
Coefficient of multiple determination R2. |
.["Ra2"] |
Adjusted coefficient of multiple determination Ra2. |
.["Residual"] |
Residuals. |
.["ResidualSum"] |
Sum of residuals. |
.["Solution"] |
The parameters found. |
.["SSE"] |
Absolute residual sum of squares. |
.["SSER"] |
Relative residual sum of squares. |
.["SSR"] |
Regression sum of squares. |
.["SST"] |
Total sum of squares. |
.["Status"] |
Status output of the algorithm. |
You can also use the syntax Formula.Elementname. However, in this case you need to consider that the properties of the formula, which can be accessed in the same way, have priority over list elements with the same name. This applies, for instance, to the element R2.
Available in
FlexPro Basic, Professional, Developer Suite
Examples
Dim list = NonLinCurveFit(MODEL_EXP_EXPONENTIAL_DECAY2, Ag, {13.33,980.56,33.92,133.80,188.28}, , _
NLCF_WEIGHTING_DATA, , NLCF_SCALING_NONE, , NLCF_OUTPUT_ALL, _
[<MaximumNumberOfFunctionCalls> 100, _
<XTolerance> 1e-008, _
<YTolerance> 1e-008, _
<FTolerance> 1e-015, _
<StepBound> 1e+002], _
NLCF_ALGORITHM_FULLNEWTON, _
[<NumberOfPeaks>1, _
<BaseLine>NLCF_BASELINE_NONE , _
<FixedParameters>{FALSE,FALSE,FALSE,FALSE,FALSE}, _
<SharedParameters>{FALSE,FALSE,FALSE,FALSE,FALSE}])
Approximates the signal 'Ag' with the Exponential decay (variant 2) model. The result of the calculation is a list with all available output. This is an example from the Non-Linear Curve Fitting Tutorial.
list.["PredictedValues"]
Results in the data modeled.
NonLinCurveFit(MODEL_EXP_EXPONENTIAL_DECAY2, Ag, {13.33,980.56,33.92,133.80,188.28})
Also results in the data modeled. This is a simplified function call for the example above that uses the default values.
NonLinCurveFit("Dim a = p[0]\r\n _
Dim b = p[1]\r\n _
Dim c = p[2]\r\n _
a + b * x + c * x^2", _
Data, {1,1,0,0}, , , , , , , [<MaximumNumberOfFunctionCalls> 300])
Approximates the 'data' data set using the custom model a + b * x + c * x2. A maximum of 300 iterations is permitted.
NonLinCurveFit("Dim a = p[0]\r\n _
Dim b = p[1]\r\n _
Dim s1 = d.[0]\r\n _
Dim s2 = d.[1]\r\n _
a * s1 + b * s2", _
Data, {1,1}, , , , , , , [<MaximumNumberOfFunctionCalls> 300], , [<AuxData> [Series1, Series2] ])
Approximates the 'Data' data set with the custom model a * Series1 + b * Series2. The two data series 'Series1' and 'Series2' are passed as a list with two elements.
See Also
Non-Linear Curve Fitting Analysis Object
Non-Linear Curve Fitting Tutorial