IDMFitter Interface

Version: 1.0
Dispatch interface for DMFitter Object

GUID: {673AB002-9A0B-11D4-B2A4-FD6847C75367}

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.

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

Syntax:
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.

Syntax:
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, Chi2 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 Chi2 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 S

Example 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 sub

For 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.

Syntax:
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 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"

Syntax:
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).

Syntax:
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.

Syntax:
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.

Syntax:
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.

Syntax:
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.

Syntax:
r/o property Deviation: Double

Read this property after you finish fitting to know how good is your fit. The smaller values of deviation (Chi2 for LM) correspond to the better fitting results.

Syntax:
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.

Syntax:
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.

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

Syntax:
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 Chi2 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.

Syntax:
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, Chi2 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 range 10-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