weisang.com > Documents Articles > NonLinCurveFit (FPScript)

FlexPro Documentation

NonLinCurveFit (FPScript)

21.09.2021

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:

Constant	Meaning
NLCF_WEIGHTING_NONE	No weighting.
NLCF_WEIGHTING_RELATIVE	Relative weighting with 1 / Y2.
NLCF_WEIGHTING_POISSON	Poisson weighting with 1 / Y.
NLCF_WEIGHTING_DATA	If the data are present as a data matrix or a signal series, then the weighting is with 1 / σ2; otherwise, there is no weighting.
NLCF_WEIGHTING_CUSTOM	Weighting with 1 / σ2; σ2 is specified.

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:

Constant	Meaning
NLCF_SCALING_NONE	No scaling.
NLCF_SCALING_ADAPTIVE	Adaptive scaling. For each iteration, the parameters are scaled based on the Jacobian matrix.
NLCF_SCALING_CUSTOM	Custom scaling.
NLCF_SCALING_BOUNDS	Scaling based on bounds: 1 / Maximum(Absolute(Lower Bounds Parameter), Absolute(Upper Bounds Parameter)) (*)
NLCF_SCALING_INITIAL	Scaling from initial Jacobian matrix. This scaling corresponds to the adaptive scaling. However, the parameters are only scaled before the first iteration. (*)

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:

Constant	Meaning
+ NLCF_OUTPUT_ALL	All available output.
+ NLCF_OUTPUT_AVERAGE_RESIDUAL	Average residual. The result is a 64-bit floating point value.
+ NLCF_OUTPUT_BASELINE	Baseline for models with several peaks. The result is a signal series each with m 64-bit floating point values.
+ NLCF_OUTPUT_CONFIDENCE95	95% confidence band. The result is a data series or a signal with m 64-bit floating point values or, for several dependent variables, a list. (*)
+ NLCF_OUTPUT_CONFIDENCE99	99% confidence band. The result is a data series or a signal with m 64-bit floating point values or, for several dependent variables, a list. (*)
+ NLCF_OUTPUT_CONFIDENCE999	99.9% confidence band. The result is a data series or a signal with m 64-bit floating point values or, for several dependent variables, a list. (*)
+ NLCF_OUTPUT_CONFIDENCE95_PARA	95% confidence intervals of parameters. The result is a data series with n 64-bit floating point values. (*)
+ NLCF_OUTPUT_CONFIDENCE99_PARA	99% confidence intervals of parameters. The result is a data series with n 64-bit floating point values. (*)
+ NLCF_OUTPUT_CONFIDENCE999_PARA	99.9% confidence intervals of parameters. The result is a data series with n 64-bit floating point values. (*)
+ NLCF_OUTPUT_CORRELATION	Correlation matrix. The result is an n x n matrix with 64-bit floating point values. (*)
+ NLCF_OUTPUT_COVARIANCE	Covariance matrix. The result is an n x n matrix with 64-bit floating point values. (*)
+ NLCF_OUTPUT_ERROR_VARIANCE	Error variance. The result is a 64-bit floating point value.
+ NLCF_OUTPUT_ITERATIONS	Number of iterations needed. The result is a 32-bit integer.
+ NLCF_OUTPUT_PARAMERROR	Standard error of parameters. The result is a data series with n 64-bit floating point values. (*)
+ NLCF_OUTPUT_PEAKS	Peak curves for models with several peaks. The result is a signal series each with m 64-bit floating point values.
+ NLCF_OUTPUT_PREDICTION95	95% prediction band. The result is a data series or a signal with m 64-bit floating point values or, for several dependent variables, a list. (*)
+ NLCF_OUTPUT_PREDICTION99	99% prediction band. The result is a data series or a signal with m 64-bit floating point values or, for several dependent variables, a list. (*)
+ NLCF_OUTPUT_PREDICTION999	99.9% prediction band. The result is a data series or a signal with m 64-bit floating point values or, for several dependent variables, a list. (*)
+ NLCF_OUTPUT_PREDICTED_VALUES	The data modeled. The result is a data series or a signal with m 64-bit floating point values or, for several dependent variables, a list.
+ NLCF_OUTPUT_R2	Coefficient of multiple determination R2. The result is a 64-bit floating point value.
+ NLCF_OUTPUT_RA2	Adjusted coefficient of multiple determination Ra2. The result is a 64-bit floating point value.
+ NLCF_OUTPUT_RESIDUAL	Residuals. The result is a data series or a signal with m 64-bit floating point values or, for several dependent variables, a list.
+ NLCF_OUTPUT_RESIDUAL_SUM	Sum of residuals. The result is a 64-bit floating point value.
+ NLCF_OUTPUT_SOLUTION	The parameters found. The result is a data series with n 64-bit floating point values.
+ NLCF_OUTPUT_SSE	Absolute residual sum of squares. The result is a 64-bit floating point value.
+ NLCF_OUTPUT_SSER	Relative residual sum of squares. The result is a 64-bit floating point value.
+ NLCF_OUTPUT_SSR	Regression sum of squares. The result is a 64-bit floating point value.
+ NLCF_OUTPUT_SST	Total sum of squares. The result is a 64-bit floating point value.
+ NLCF_OUTPUT_STATUS	Status output of the algorithm. The result is a 32-bit integer.

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:

Constant	Meaning
<MaximumNumberOfFunctionCalls>	Maximum number of function calls allowed for the calculation. The default is 100.
<XTolerance>	X convergence tolerance. The default is 10-8.
<YTolerance>	Relative function convergence tolerance. The default is 10-8.
<FTolerance>**	Absolute function convergence tolerance. The default is 10-15.
<GTolerance>*	Tolerance for the cosine of the angle between the columns of the current Jacobian matrix and the corresponding residual vector. The default is 10-8.
<StepBound>	Step bound. The default is 100.

* 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:

Constant	Meaning
NLCF_ALGORITHM_FULLNEWTON	Full Newton algorithm. (NL2SOL)
NLCF_ALGORITHM_LEVENBERGMARQUARDT	Levenberg-Marquardt algorithm. (MINPACK)

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:

Constant

Meaning

Number of peaks of the model to be calculated. This option is only relevant for peak models.

Specifies which model is to be used for the baseline. The default is NLCF_BASELINE_NONE. This option is only relevant for peak models. The selected model is added to the peak model.The argument can have the following values:

Constant	Model
NLCF_BASELINE_NONE	No model
NLCF_BASELINE_CONSTANT	A
NLCF_BASELINE_LINE	A+Bx
NLCF_BASELINE_QUADRATIC	A+Bx+Cx2
NLCF_BASELINE_CUBIC	A+Bx+Cx2+Dx3
NLCF_BASELINE_POLY4	A+Bx+Cx2+Dx3+Ex4
NLCF_BASELINE_POLY5	A+Bx+Cx2+Dx3+Ex4+Fx5

A data series with Boolean values that specify whether a parameter is variable or not. The number of values corresponds to the number of model parameters multiplied by the number of peaks. TRUE means fixed, FALSE means variable.

A data series with Boolean values that specify whether a parameter is to be used for a peak model together with several peaks. This option is only relevant for several peaks. TRUE means share use. The number corresponds to the number of model parameters.

Any data that can be passed as an option to the custom model as argument 'd'.

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.

FlexPro Documentation

NonLinCurveFit (FPScript)

Syntax

Remarks

Available in

Examples

See Also

You might be interested in these articles

Weisang GmbH