IDMFitter interface provides access to the DMFitter ActiveX control and includes 2 main methods: LinearFit and LMFit, and a set of properties. Typically you set properties, invoke fitter and read properties to obtain the results of fitting.
Notice that both fitters share the same set of parameters. So that, you have to initialize properties and retrieve results differently. See descriptions of interface elements and demonstration applications included in the installation for more details.
Kind | Name | ID | Description |
LinearFit | 201 | Invoke Linear Fitter | |
LMFit | 202 | Invoke Levenberg-Marquardt NLSF | |
Expression | 203 | Fitting expression, fitter object or linear basis | |
X | 204 | Array of X coordinates | |
Y | 205 | Array of Y coordinates | |
Weight | 206 | Array of X,Y points weights | |
WeightType | 207 | Type of weight (only LM) | |
ResultCode | 208 | Detailed result of LinearFit/LMFit | |
Deviation | 209 | Deviation or Chi^2 | |
Parameters | 210 | Array of fitting parameters | |
ParamCount | 211 | Number of fitting parameters (1..N) | |
Sigmas | 212 | Array of LM sigmas / parameter fix flags | |
Iterations | 213 | Maximal / actual number of LM iterations | |
Options | 214 | LM fitter options |
function LinearFit: Boolean |
In DM2003, Linear fitting is not so interesting as LM, but in some cases it may be more suitable. One of its main advantages is speed: linear fitting does not require iterative calculations. X,Y arrays are curve to be fitted, NumTerms and BasisType define fitting expression, parameter values returned in Solution array.
Example:
function LinFit(BasisType, NumTerms) dim X,Y,NumPoints,Solution,Deviation,ResCode dim I,FL,Ser,Cont,CX,CY,D,S set Ser=Server.ActiveDocument.Plot.CurrentSerie set Cont=Ser.Container FL=Ser.FirstLine NumPoints=Ser.LastLine-FL+1 CX=Ser.XColumn-1 CY=Ser.YColumn-1 ReDim X(NumPoints-1) ' Redim(upper index=np-1!) ReDim Y(NumPoints-1) for I=1 to NumPoints ' copy data being fitted D=Cont.Items(FL+I-1) X(I-1)=D(CX) Y(I-1)=D(CY) next call Server.LinearFit(X,Y,NumTerms,BasisType,Solution,Deviation,ResCode) S="" for I=1 to NumTerms S=S & "Coef[" & I & "]=" & Solution(I-1) & vbCrLf next S=S & "Rescode=" & ResCode & vbCrLf & "Deviation=" & Deviation LinFit=S end function sub FitTest Server.Notes.AddLine "=======================================" Server.Notes.AddLine(LinFit(1,3)) end sub
In DMFitter ActiveX control, function LinearFit invokes linear fitter. It has no parameters. The returned value is True if fitting session was successful; otherwise it returns False. You can obtain more details from ResultCode property. Before you call LinearFit, you must initialize following properties: X, Y, Expression and ParamCount. After fitting you can obtain results from the following properties: Parameters, Deviation and ResultCode.
function LMFit: Boolean |
In DM2003, this method performs up to NIter Levenberg-Marquardt iterations, actual number of iterations returned in this parameter. X, Y - variant arrays with curve to be fitted; W - point weights (also variant array). WType must be one of values in the WeightType enumeration.
Expression includes all standard functions (see the list of available functions), independent variable is named CX, parameters are named p1, p2, etc. Initial parameter values passed in the Params array, and any parameter may be fixed if you set corresponding Sigma[] value to -1, otherwise Sigma[] must be 0. The number of parameters in the Expression must be equal to the size of Params and Sigma arrays. After all iterations are completed, you should read parameters from Params array, their deviations from Sigma array, Chi^{2} and result code from appropriate parameters. Result codes defined in the FitResult Enumeration.
In addition, Expression may be also an object that implements two methods for calculating function and derivative. This feature may remarkably improve fitter performance. Method signatures must be exactly as shown in the Example 2 (see below).
There is an useful option: you may allocate exactly 3 extra numbers in the Sigma array for additional ParDel, ChiDel and Deriv parameters. First two determine Parameters and Chi^{2} convergence thresholds, and third (Deriv) used to calculate numeric derivative for Expression.
Example 1:
dim X(999), Y(999), Params(3), Sigma(3), NIter, ChiSqr, ResCode ' initialize X, Y input vectors for I=0 to UBound(X) X(I)=I Y(I)=12.345 + 3*I -0.2*I^2 + 0.045678*I^3 next ' initialize parameters and deviations for I=0 to 3 Params(I)=1 Sigma(I)=0 next NIter=30 ' perform fitting (point weights are not used) call Server.LMFit(X, Y, 0, 0, "p1+p2*cx+p3*cx^2+p4*cx^3", _ Params, Sigma, NIter, ChiSqr, ResCode) ' display result S="" for I=0 to 3 S=S & Params(I) & vbCrLf next MsgBox SExample 2:
' hardcoded polynomial fit class MyFitterClass function CalculateFunction(X, Params) CalculateFunction=Params(0)+Params(1)*X+Params(2)*X^2+Params(3)*X^3 end function function CalculateDerivative(X, Params, Sigma) dim Result(3) Result(0)=1 Result(1)=X Result(2)=X^2 Result(3)=X^3 CalculateDerivative=Result end function end class dim F set F=new MyFitterClass sub RunFitting dim X(999), Y(999), Params(3), Sigma(3), NIter, ChiSqr, ResCode ' initialize X, Y input vectors for I=0 to UBound(X) X(I)=I Y(I)=12.345+3*I-0.2*I^2+0.045678*I^3 next ' intialize parameters and deviations for I=0 to 3 Params(I)=1 Sigma(I)=0 next NIter=30 ' perform fitting (point weights are not used) call Server.LMFit(X, Y, 0, 0, F, Params, Sigma, NIter, ChiSqr, ResCode) ' display result S="" for I=0 to 3 S=S & Params(I) & vbCrLf next MsgBox S end subFor DMFitter ActiveX control, function LMFit invokes non-linear (Levenberg-Marquardt) fitter. It has no parameters. The returned value is True if fitting session was successful; otherwise it returns False. You can obtain more details from ResultCode property. Before you call LMFit, you must initialize following properties: X, Y, Expression, ParamCount, Parameters, Sigmas, Iterations and WeightType. In addition, you can initialize following properties: Weight and Options. After fitting you can obtain results from the following properties: Parameters, Sigmas, Iterations, Deviation and ResultCode.
Notice that unlike linear fitter, LM fitting is iterative procedure by its nature and may take a lot of time, especially for large number of parameters and complex expressions.
property Expression: Variant |
For DM2003 plot axis, you may transform all series simultaneously if you assign valid expression to this property. See details about expression syntax and allowed arguments and function names.
For DMFitter ActiveX control, Expression property should be defined before you start fitting. There are several possible situations:
- For predefined linear models possible values of this property are listed in the LinearBasisType Enumeration;
- You can define arbitrary linear basis if you assign to this property a string expression composed from basis members (expressions dependent only on CX parameter) divided by vbCrLf delimiter (see TestLinearGFit.htm demo for details);
- If you assign -1 (or True) to this property, DMFitter will invoke OnGetLinearBasis event handler to calculate user-defined basis members (see TestLinearEFit.htm demo);
- For LM fitter you can provide DM2003-compatible string expression (see details about expression syntax); in addition, the components of multidimensional independent variable are denoted by "cx1", "cx2", .. "cx25".
- Also you can define custom LM fitting object (see TestFitObject.htm demo for more information);
- If you assign -1 (or True) to this property, LM fitter will rely on OnGetLMFunction and OnGetLMDerivative event handlers to obtain values of function and partial derivatives. Value of -2 instructs LM fitter to invoke only OnGetLMFunction event and perform differentiation numerically (see TestLMFitEvents.htm and TestLMFitEJS.htm examples).
For worksheets, this property is index-based and determine column expressions. These expressions may be used to recalculate dynamically the contents of appropriate column. Notice that you can assign expressions to any column, even those that has no data! The syntax and parameter set for column expressions are the same as for plot series.Example:
Server.CreateDocument Server.InstallPath & "samples\data_1.dat" Server.ExecuteCommand "ShowWorksheetAction" Server.ActiveDocument.Worksheet.Expression(3)="a+b"
property X: Variant |
Assign to this property variant array of X coordinates of your data points before you start linear or LM Fitter. For LM fitter, you also can provide 2D variant array, where first index enumerates data rows, and second index - components of X vector (see Test2DLMFit.htm sample for more details).
Keep in mind that for LMFitter object, you may do not initialize and use X if you assign fitting object to the Expression property. For this coclass, implementation of fitting object differs from DMFitter for better performance (see TestLMFitter.htm sample). String-type expressions or event handlers are 100% compatible with DMFitter and require an array of X values (possibly 2D).
property Y: Variant |
Assign to this property variant array of Y coordinates of your data points before you start linear or LM Fitter. Notice that number of elements in X, Y and Weight arrays must be the same.
property Weight: Variant |
Point weights for LM fitter. You must assign this property before you start fitting if you have defined non-zero WeightType. Otherwise you can leave this property unassigned.
property WeightType: Long |
Specify type of weighting for LM fitter (value of 0 disables point weights). If you set non-zero value, you must initialize Weight property with an array of point weights. Other possible values of this property are listed in the WeightType Enumeration.
For LMFitter object, WeightType is a boolean property and it just indicates whether Weight property should be initialized and used.
r/o property ResultCode: Long |
This property should be analyzed after fitting session if you need more details about results. Possible values are listed in the FitResult Enumeration. For LMFitter object, additional ResultCode=7 was introduced to indicate problems with dynamically loaded LM engine core (lmhelper.dll). Also after LMFit ResultCode may be set to 0 if further error reduction is impossible.
r/o property Deviation: Double |
Read this property after you finish fitting to know how good is your fit. The smaller values of deviation (Chi^{2} for LM) correspond to the better fitting results.
property Parameters: Variant |
For LM fitter, you must provide initial values of fitting parameters before you start fitting session. Notice that LM algorithm (like other nonlinear regression algorithms) requires properly initialized parameters to obtain desirable results. It does not calculate values of parameters as in case of linear fitter; instead, it just improves initial values. Notice that parameters are updated dynamically at each iteration. You also can define parameters convergence threshold (see Options property).
For Linear fitter, you just read this property to obtain an array of fitting parameters.
After you finish fitting, read this property to get an array of parameter values.
property ParamCount: Long |
The number of parameters must be initialized before you start fitting. Keep in mind that for LM fitter the size of Parameters and Sigmas arrays must correspond with the value of ParamCount. For linear fitter, this property holds the number of terms for user-defined, polynomial and Fourier basis types.
property Sigmas: Variant |
Before you start fitting session, you must define parameter fixing flags. Set appropriate flag to -1 (true) if you would like to fix initial value of the parameter, otherwise set its value to 0 (false). After LM finishes, you can read this property to obtain an array of individual parameter deviations.
For LMFitter, Sigmas also may be used to apply box constraints as shown below:
Examples:
' 3- column matrix Redim P(3,2) for i=0 to 3 P(i,0)=0 if i=0 then P(i,1)=1 else P(i,1)=-1e308 P(i,2)=1e308 next ' array of strings (JS): Redim P(3) for i=0 to 3 if i=0 then P(i)="0 1 1e308" else P(i)="0 -1e308 1e308" next
property Iterations: Long |
Specify maximal number of LM fitter iterations. Notice that this property increments after each LM iteration, so that you can easily monitor fitting progress. If you define Chi^{2} or Parameters convergence thresholds (see Options property), LM fitter may stop before given number of iterations will be reached.
Notice that for LMFitter object iterations number obtained inside the OnProgress event handler may be greater than actual.
property Options: Variant |
For DMFitter, Options give you additional control over LM fitting session. Assign to this property variant array of exactly 3 values (Parameters convergence threshold, Chi^{2} convergence threshold and derivative dX) or something other (e.g. a string "no") if you prefer default values. You can also use zero values if you would like to change not all options.
LMFitter object requires variant (or JS) array of exactly 5 constants: initial value of damping factor Lambda (
λ~10^{-3}..10^{-4} ), three convergence thresholds (values in the range10^{-10}..10^{-20} ) and derivative dX (10^{-6}..10^{-16} ). Also you can pass zeroes for default values or arbitrary string if you do not want to use this property.For DMApplication, this property allows you to change various application settings.
Example:
s="FixDesktopFilenames=" & _ Server.Options("FixDesktopFilenames") & vbCrLf & _ "ExpSettings=" & Server.Options("ExpSettings") & _ vbCrLf & "PropertySheetClass=" & _ Server.Options("PropertySheetClass") & vbCrLf & _ "EnableDoubleBufferedPlot=" & _ Server.Options("EnableDoubleBufferedPlot") _ & vbCrLf & "ToolBarCheckBox=" & _ Server.Options("ToolBarCheckBox") & vbCrLf & _ "StatusLineCheckBox=" & _ Server.Options("StatusLineCheckBox") & vbCrLf & _ "MergeDMWNotes=" & Server.Options("MergeDMWNotes") _ & vbCrLf & "CopyPlotFrame=" & _ Server.Options("CopyPlotFrame") & vbCrLf & _ "DoubleFloat=" & Server.Options("DoubleFloat") _ & vbCrLf & "UseBalloonDisplayMessage=" & _ Server.Options("UseBalloonDisplayMessage") MsgBox s