BiErfFit provides a tool to fit a hysteresis curve simultaneously with two linear combinations of error functions. For brevity, we call the curve which forms the left part of the hysteresis, curve α, and that which forms the right part, curve β. The model used to fit each curve is given by:

f(x) ~ Baseline + errorfunc1(x) + errorfunc2(x) + ... + errorfuncN(x)

where each error function is a derived form of the standard erf function as given by:

errorfunc(x) ~ (Height/2) (1 + erf( 2 sqrt(ln(2))(x - Center)/Width))

Baseline, Center, Width, and Height are the fit coefficients.

• The algorithm in fit.m needs an improvement, particularly for dealing with cases that involve curve fitting with more than one error functions.

This software is licensed under the GNU General Public License (version 3).

• MATLAB R2015b - R2018a

• MATLAB Curve Fitting Toolbox
• MatCommon
• PeakFit
• MatGraphics - required for doing the examples

1. Download or git-clone this repository and other repositories listed in the Requirements.
2. Add the repositories to the MATLAB's search path via addpath(genpath( ... )) OR this version control system.

Construct the BiErfFit object in the following ways, and the fit results will be populated in the object's public properties.

obj = BiErfFit(Data, ... Name-Value ...)

OR

obj = BiErfFit(XData, YData, ... Name-Value ...)

OR

% Create an empty BiErfFit object.
obj = BiErfFit();

% Specify the data points and curve-fit settings via property assignments.
obj.XData = ... ;
obj.YData = ... ;
obj.Property1Name = Value1;
obj.Property2Name = Value2;
...

% Perform the curve fitting by reinstantiating the BiErfFit object.
obj = BiErfFit(obj);

Data must be specified as a cell containing two elements: the first for curve α and the second for curve β. Each element must be a two-column (or two-row) matrix where the first column (or first row) is the X data points and the second column (or second row) is the Y data points. In the alternative syntax, XData and YData are respectively the X and the Y data points, also specified as a two-element cell; but instead of matrix, the elements must be a vector.

The curve-fit settings can be specified after the mandatory arguments in Name-Value syntax, e.g. BiErfFit(Data, 'Window', [10,90], 'NumErfs', [2,3]). If no settings are specified, the algorithm will attempt to fit the hysteresis curve using the default settings. The default option fits curve α and curve β with one error function each, and may not produce a good fit.

Any of the public properties can be specified as arguments in Name-Value syntax during the object construction. Specifying other things as Name-Value arguments will return an error.

The fitting algorithm works sufficiently well if the start points of the fitting are specified as done in the following example. Finding the right start points involves some guess work and trial and error. The accuracy of the fit can be improved by specifying the lower and upper bounds of the fitting. The figure shown below is the reflectivity switching of VO2:Er (Lim2014). The left curve was fitted with two error functions, and the right, with one error function, by using the command:

Fit=BiErfFit(Data, ...
    'BaselineStart', ... ,...
    'CenterStart', { ... , [ ... , ... ]}, ...
    'HeightStart', { ... , [ ... , ... ]}, ...
    'WidthStart', { ... , [ ... , ... ]});

The full code is given in Examples/VO2Er_transition.m. Two-element vectors are supplied to the start points for the right curve because there are two error functions to be fitted.

• Data, XData, YData: The data points of the curve to be fitted.
• Window: A vector of length two [a, b] that limits the fitting to only the data points whose X coordinates lies within [a, b].
• NumErfs: The number of error functions to be fitted to curve α and curve β. Specified as a positive integer vector of length two, [n_α, n_β]. If the corresponding start points, lower, or upper bounds are set with vectors of length greater than n_α (or n_β), then n_α (or n_β) will be incremented to adjust to the maximum length of these vectors. If the maximum length of these vectors is less, then these vectors will be expanded and filled with the default values. NumErfs defaults to [1, 1].

• (Read-only) Center, Height, Width: A cell containing two elements: a 3-by-n_α matrix and a 3-by-n_β matrix. Each matrix stores the fit results for the center, height, and width, respectively, for curve α or curve β. Each column in the matrices correspond to the fit results for a particular error function. The first row holds the values at convergence, and the second (third) row holds the 95% CI lower (upper) bounds.
• (Read-only) Baseline: A 3-by-1 vector that stores the fit results for the baseline. The first row holds the values at convergence, and the second (third) row holds the 95% CI lower (upper) bounds.
• (Read-only) Asymptote: The lower and upper asymptotes to which the combined error functions converge at x = ±∞. Given as a 3-by-2 matrix, where the first (second) column holds the values for the lower (upper) asymptote, the first row holds the values at convergence, and the second (third) row holds the 95% CI lower (upper) bounds.
• (Read-only) DynamicRange: The ratio of the increase or decrease in y as x goes from -∞ to +∞. Given as a 3-by-1 vector, where the first row holds the values at convergence, and the second (third) row holds the 95% CI lower (upper) bounds.
• (Read-only) HysteresisWidth: The hysteresis width. Given as a 3-by-1 vector, where the first row holds the values at convergence, and the second (third) row holds the 95% CI lower (upper) bounds.
• (Read-only) TransitionWidth: The transition width. Given as a cell containing two elements. Each element is a 3-by-1 vector holding the values for curve α or curve β, respectively. The first row in each vector holds the values at convergence, and the second (third) row holds the 95% CI lower (upper) bounds.
• (Read-only) RelStDev: The relative standard deviation of the fit results.
• (Read-only) CoeffDeterm: The coefficient of determination of the fit results.
• (Read-only) AdjCoeffDeterm: The degree-of-freedom adjusted coefficient of determination of the fit results.
• (Read-only) NumFunEvals: The number of function evaluations.
• (Read-only) NumIters: The number of iterations.
• (Read-only) ExitFlag: The exit condition of the algorithm. Positive flags indicate convergence, within tolerances. Zero flags indicate that the maximum number of function evaluations or iterations was exceeded. Negative flags indicate that the algorithm did not converge to a solution.

• CenterStart, WidthStart, HeightStart: The start points for the center, width, and height, respectively. Specified as a cell containing two vectors: the first for curve α and the second for curve β. Can also be specified as a vector of length two, if NumErfs is intended to be [1, 1].
• BaselineStart: The initial value for the baseline coefficient. Specified as a real scalar.

• CenterLow, WidthLow, HeightLow: The lower bounds for the center, width, and height, respectively. Specified as a cell containing two vectors: the first for curve α and the second for curve β. Can also be specified as a vector of length two, if NumErfs is intended to be [1, 1].
• BaselineStart: The lower bound for the baseline coefficient. Specified as a real scalar.

• CenterLow, WidthLow, HeightLow: The upper bounds for the center, width, and height, respectively. Specified as a cell containing two vectors: the first for curve α and the second for curve β. Can also be specified as a vector of length two, if NumErfs is intended to be [1, 1].
• BaselineStart: The upper bound for the baseline coefficient. Specified as a real scalar.

• (Read-only) Method = 'NonLinearLeastSquares'; The method used for the fitting.
• Robust: The type of the least-squares method to be used in the fitting. Avaliable values are 'off', 'LAR' (least absolute residual method), and 'Bisquare' (bisquare weight method). Defaults to 'off'.
• Algorithm: The algorithm to be used in the fitting. Available values are 'Lavenberg-Marquardt', 'Gauss-Newton', or 'Trust-Region'. Defaults to 'Trust-Region'.
• MovMeanWidth: The window width of the moving average used for smoothing the curve in order to filter out the noise before finding the maximas. This parameter is used only when CenterStart is not given. This parameter can be set as a positive integer which specifies the width in terms of the number of data points, or a real scalar between [0, 1] which specifies the width as a fraction of the total number of data points. Defaults to 0.02.
• DiffMaxChange: The maximum change in coefficients for finite difference gradients. Defaults to 0.1.
• DiffMinChange: The minimum change in coefficients for finite difference gradients. Defaults to 1e-8.
• MaxFunEvals: The allowed maximum number of evaluations of the model. Defaults to 1e5.
• MaxIters: The maximum number of iterations allowed for the fit. Defaults to 1e3.
• TolFun: The termination tolerance on the model value. Defaults to 1e-6.
• TolX: The termination tolerance on the coefficient values. Defaults to 1e-6.

• disp: Displays the options, results, error and performance of the fitting.
• model: Returns the reconstructed data points (model) using the fit results. See @BiErfFit/model.m for more info.

• fnerf: The error function. See @BiErfFit/fnerf.m for more info.
• fngaussian: The Gaussian function. See @BiErfFit/fngaussian.m for more info.