Least-squares fitting of EPR and other data.

esfit(data,fcn,p0,vary)
esfit(data,fcn,p0,lb,ub)
esfit(___,FitOpt)
fit = esfit(___)

See also the user guide on least-squares fitting.

esfit fits EPR data simulated with any EasySpin function, e.g. garlic, pepper, chili, etc. to experimental spectral data using least-squares fitting algorithms and calculates uncertainties (error bars) for the fitted parameters. Additionally, it can also be used for fitting of any other type of data, given a user-defined model function. Global fitting of multiple data sets is supported for user-defined simulation and model functions (see user guide for details).

The input parameters are the following:

• data is a 1D array containing the experimental spectral data or a cell array containing multiple data sets (in the latter case, a custom simulation function returning a cell array of calculated data needs to be defined for fitting).

• fcn is the function handle of a simulation or model function: @garlic, @pepper, @chili, @saffron, @salt, or a user-supplied custom model function that takes an input parameter vector p and returns simulated data, datasim = fcn(p).

  For global fitting of multiple data sets, a custom model function is required, which takes input parameters and returns a cell array of simulated data sets with dimensions matching the corresponding experimental data sets. Custom model functions based on EasySpin functions can be used with a spin system and experimental structure as input, which must be adapted internally for a series of different simulations that are then returned in a cell array (see the user guide for an example).

• p0 defines the starting values for the fitting parameters.

  For EasySpin functions and custom functions based on them, provide the spin system structure containing all the parameters of the spin system, the experimental parameter structure and, if desired, a simulation options structure Opt.

  esfit(data,@pepper,{Sys0,Exp0},{varySys})
  esfit(data,@pepper,{Sys0,Exp0,Opt},{varySys})
  esfit(data,@pepper,{Sys0,Exp0,Opt},{varySys},FitOpt)
  

  For other functions, p0 is an n-element vector.

  userfcn = @(p) modelfunction(p);
  esfit(data,userfcn,p0,vary)
  

  For parameters that are to be varied during the fitting process, the values in p0 represent the starting values of the fit and the centers of the search ranges, if the fitting parameter variation is defined in vary.

  For multi-component systems, Sys0 is a cell array of spin system structures, e.g. {Sys1,Sys2} for a two-component system. The weights for the different components are included in each component structure, e.g. Sys1.weight = 0.7 and Sys2.weight = 0.3. The weights are relative (0.7 and 0.3 is the same as 14 and 6) and can be included in the fit. If weight is omitted, it is assumed to be 1. There is no limit on the number of components.

  esfit(data,@pepper,{{Sys1,Sys2},Exp0},{{varySys1,varySys2}})
  

  Exp0 contains the experimental parameters needed for the simulation. For EPR spectral simulations, make sure to specify the field or frequency range and the number of points you used for the experimental data in Exp.Range or Exp.mwRange. If you let the simulation function automatically pick a range, it will likely be different from the experimental one, and esfit cannot do its work. For example, if x is the experimental field range, use Exp.Range = [min(x) max(x)] and Exp.nPoints = numel(x).

  Opt contains simulation options that are forwarded directly to the simulation function. Refer to the documentation of chili, garlic, pepper, and salt for details.

• vary contains the maximum variations for the parameters allowed during fitting.

  For EasySpin-style functions, this should mirror the p0 input style, e.g. {SysVary} or {SysVary,ExpVary} if experimental parameters should also be varied in the fitting. For EasySpin functions, if a spin system or experimental parameter should be included in the fitting, give it a non-zero value in this structure. If it should not be included, set its value in this structure to zero, or don't include it at all.

  Sys0.lwpp = 5;
  SysVary.lwpp = 2;    % the line width is searched over a range of about 3 to 7
  SysVary.lwpp = 0;    % the line width is kept constant at the value given in Sys0
  

  For multiple components, SysVary should be a cell array containing one structure per component, e.g. {SysVary1,SysVary2} for two components. If none of the parameters of a component are varied in the fit, [] can be specified, e.g. {SysVary1,[]} for a two-component fit where only parameters of the first component are varied.

• lb and ub contain the lower and upper bounds for variation of the parameters allowed in the fitting and can be used instead of vary. For EasySpin-style functions, this should mirror the p0 input style, e.g. {lbSys,lbExp} and {ubSys,ubExp}.

• FitOpt is a structure containing settings for the optimization algorithms used in esfit. The possible settings are described further down on this page.

If no output is requested, esfit starts an interactive user interface that allows extensive control over the fitting process and also allows the export of the fitting results to the workspace. In the UI, the fitting algorithm can be changed, parameters can be excluded from the fit, and multiple fit sets can be stored.

If esfit is called with one output, it runs without a user interface, and returns a structure fit containing the fit results. A similar structure is also returned if esfit is used with the graphical user interface and a set of parameters is exported.

The structure FitOpt contains fitting options. The most important ones select the fitting algorithm and the function to use for computing the residuals:

FitOpt.Method = 'simplex fcn';
FitOpt.Method = 'genetic int';

There are more options which are recognized by all fitting algorithms:

Opt.x = linspace(350,370,1000);

Each of the available fitting algorithms can be fine-tuned using a set of parameters.

Parameters for Nelder-Mead downhill simplex:

Parameters for Levenberg-Marquardt:

Parameters for Monte Carlo:

Parameters for the genetic algorithm:

Parameters for the grid search:

Vary.g = [0 0.001 0]; Vary.lw = 0.2;

Opt.GridSize = 10;   % 10 points for each parameter, making 100 grid points total
Opt.GridSize = [20 3]; % 10 points along g and 3 along lw, giving a total of 60

Parameters for the particle swarm:

Here is a very simple example. Assume the experimental data have been loaded into data. Then the following code performs a least-squares fitting using the Nelder-Mead downhill simplex algorithm.

Exp.mwFreq = 9.5; % GHz
Sys0.g = [2.1 2.2]
Sys0.lwpp = 0.1; % mT
SysVary.g = [0.05 0.02];
esfit(data,@pepper,{Sys0,Exp},{SysVary});

Global fitting of multiple data sets can be performed similarly, but requires definition of a custom function that returns the same number of data sets as the provided ones. Assuming data to be a cell array containing data sets recorded at X- and Q-band frequencies, the following code allows global fitting of both with the same spin system structure.

Exp.mwFreqX = 9.5; % GHz
Exp.mwFreqQ = 34; % GHz
Sys0.g = [2.1 2.2]
Sys0.lwpp = 0.1; % mT
SysVary.g = [0.05 0.02];

esfit(expdata,@pepperXQ,{Sys0,Exp},{SysVary});

function data = pepperXQ(Sys,Exp)
Exp.mwFreq = Exp.mwFreqX;
data{1} = pepper(Sys,Exp);
Exp.mwFreq = Exp.mwFreqQ;
data{2} = pepper(Sys,Exp);
end

See the example section for full examples. Also, read the user guide about fitting.

chili, garlic, pepper