This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
FUNCTION EXPONENTIAL USAGE: y = exponential(x,par=p)
(See general/tools/fitting/exponential.pro)
NAME:
FIT
PURPOSE:
Non-linear least squares fit to a user defined function.
This procedure is an improved version of CURVEFIT that allows fitting
to a subset of the function parameters.
The function may be any non-linear function.
If available, partial derivatives can be calculated by
the user function, else this routine will estimate partial derivatives
with a forward difference approximation.
CATEGORY:
E2 - Curve and Surface Fitting.
CALLING SEQUENCE:
FIT,X, Y, PARAMETERS=par, NAMES=string, $
FUNCTION_NAME=string, ITMAX=ITMAX, ITER=ITER, TOL=TOL, $
/NODERIVATIVE
INPUTS:
X: A row vector of independent variables. The FIT routine does
not manipulate or use X, it simply passes X
to the user-written function.
Y: A row vector containing the dependent variable.
KEYWORD INPUTS:
FUNCTION_NAME: The name of the function to fit.
If omitted, "FUNC" is used. The procedure must be written as
described under RESTRICTIONS, below.
PARAMETERS: A structure containing the starting parameter values
for the function. Final values are also passed back through
this variable. The fitting function must accept this keyword.
If omitted, this structure is obtained from the user defined
function.
NAMES: The parameters to be fit. Several options exist:
A string with parameter names delimited by spaces.
A string array specifying which parameters to fit.
An integer array corresponding to elements within the PARAMETERS structure.
If undefined, then FIT will attemp to fit to all double precision
elements of the PARAMETERS structure.
WEIGHT: A row vector of weights, the same length as Y.
For no weighting,
w(i) = 1.0.
For instrumental weighting,
w(i) = 1.0/y(i), etc.
if not set then w is set to all one's (equal weighting)
DY: A row vector of errors in Y. If set, then WEIGHTS are set to:
W = 1/DY^2 and previous values of the WEIGHTS are replaced.
ERROR_FACTOR: set this keyword to have DY set to ERROR_FACTOR * Y.
ITMAX: Maximum number of iterations. Default = 20.
TOL: The convergence tolerance. The routine returns when the
relative decrease in chi-squared is less than TOL in an
interation. Default = 1.e-5.
NODERIVATIVE: (optional)
If set to 1 then the partial derivatives will be estimated in CURVEFIT using
forward differences.
If set to 0 then the user function is forced to provide
partial derivatives.
If not provided then partial derivatives will be determined
from the user function only if it has the proper keyword
arguments.
VERBOSE: Verbose level (0: prints only errors, 1: prints results, 2: prints each iteration)
(see "DPRINT" for more info)
MAXPRINT: Maximum number of parameters to display while iterating
(Default is 8)
SILENT: Equivalent to VERBOSE=0
KEYWORD OUTPUTS:
ITER: The actual number of iterations which were performed.
CHI2: The value of chi-squared on exit.
FULLNAMES: A string array containing the parameter names.
P_VALUES: A vector with same dimensions as FULLNAMES, that
contains the final values for each parameter. These values
will be the same as the values returned in PARAMETERS.
P_SIGMA: A vector containing the estimated uncertainties in P_VALUES.
FITVALUES: The fitted function values:
OUTPUT
Returns a vector of calculated values.
COMMON BLOCKS:
NONE.
RESTRICTIONS:
The function to be fit must be defined and called FUNC,
unless the FUNCTION_NAME keyword is supplied. This function,
must accept values of X (the independent variable), the keyword
PARAMETERS, and return F (the function's value at X).
if the NODERIV keyword is not set. then the function must also accept
the keywords: P_NAMES and PDER (a 2d array of partial derivatives).
For an example, see "GAUSS2".
The calling sequence is:
CASE 1: (NODERIV is set)
F = FUNC(X,PAR=par) ; if NODERIV is set or:
where:
X = Variable passed into function. It is the job of the user-written
function to interpret this variable. FIT does NOT use X.
PAR = structure containing function parameters, input.
F = Vector of NPOINT values of function, y(i) = funct(x), output.
CASE 2: (NODERIV is not set)
F = FUNC(X,PAR=par,NAMES=names,PDER=pder)
where:
NAMES = string array of parameters to be fit.
PDER = Array, (NPOINT, NTERMS), of partial derivatives of FUNC.
PDER(I,J) = Derivative of function at ith point with
respect to jth parameter. Optional output parameter.
PDER should not be calculated if P_NAMES is not
supplied in call. If the /NODERIVATIVE keyword is set in the
call to FIT then the user routine will never need to
calculate PDER.
PROCEDURE:
Adapted from "CURVEFIT", least squares fit to a non-linear
function, pages 237-239, Bevington, Data Reduction and Error
Analysis for the Physical Sciences.
"This method is the Gradient-expansion algorithm which
combines the best features of the gradient search with
the method of linearizing the fitting function."
Iterations are performed until the chi square changes by
only TOL or until ITMAX iterations have been performed.
The initial guess of the parameter values should be
as close to the actual values as possible or the solution
may not converge.
EXAMPLE: Fit to a gaussian plus a quadratic background:
Here is the user-written procedure to return F(x) and the partials, given x:
See the function "GAUSSIAN" for an example function to fit to.
x=findgen(10)-4.5 ; Initialize independent variables.
y=[1.7,1.9,2.1,2.7,4.6,5.5,4.4,1.7,0.5,0.3]; Initialize dependent variables.
plot,x,y,psym=4 ; Plot data.
xv = findgen(100)/10.-5. ; get better resolution abscissa.
oplot,xv,gaussian(xv,par=p) ; Plot initial guess.
help,p,/structure ; Display initial guess.
fit,x,y,func='gaussian',par=p,fit=f ; Fit to all parameters.
oplot,x,f,psym=1 ; Use '+' to plot fitted values.
oplot,xv,gaussian(xv,par=p) ; Plot fitted function.
help,p,/structure ; Display new parameter values.
names =tag_names(p) ; Obtain parameter names.
p.a2 = 0 ; set quadratic term to 0.
names = names([0,1,2,3,4]) ; Choose a subset of parameters.
print,names ; Display subset of names
fit,x,y,func='gaussian',par=p,names=names ; Fit to subset.
Please Note: Typically the initial guess for parameters must be reasonably
good, otherwise the routine will not converge. In this example the data
was selected so that the default parameters would converge.
The following functions can be used with FIT:
"gaussian", "polycurve", "power_law", "exponential", "gauss2", "igauss"
KNOWN BUGS:
Do NOT trust the P_SIGMA Values (uncertainty in the parameters) if the
the value of flambda gets large. I believe
That some error (relating to flambda) was carried over from CURVEFIT. -Davin
MODIFICATION HISTORY:
Function adapted from CURVEFIT Written, DMS, RSI, September, 1982
and last modified by Mark Rivers, U. of Chicago, Febuary 12, 1995.
Davin Larson, U of California, November 1995, MAJOR MODIFICATIONS:
- Changed FUNCTION_NAME to a function (instead of procedure) that
accepts a structure to hold the parameters. This makes the usage
much more user friendly, and allows a subset of parameters to
be fit.
- Allowed vectors and recursively searched structures to be fit as well.
$LastChangedBy: davin-mac $
$LastChangedDate: 2020-04-20 12:01:32 -0700 (Mon, 20 Apr 2020) $
$LastChangedRevision: 28593 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tools/fitting/fit.pro $
(See general/tools/fitting/fit.pro)
Crib sheet to show how to use fit routine.
(See general/tools/fitting/fit_crib.pro)
FUNCTION: GAUSS
PURPOSE:
Evaluates a gaussian function with background.
This function may be used with the "fit" curve fitting procedure.
KEYWORDS:
PARAMETERS: structure with the format:
** Structure <275ac0>, 6 tags, length=48, refs=1:
H DOUBLE 1.0000000 ; hieght
W DOUBLE 1.0000000 ; width
X0 DOUBLE 0.0000000 ; center
A0 DOUBLE 0.0000000
A1 DOUBLE 0.0000000
A2 DOUBLE 0.0000000
If this parameter is not a structure then it will be created.
USAGE:
p={h:2.,w:1.5,x0:5.0,a0:0.,a1:0.,a2:0.}
x = findgen(100)/10.
y = gaussian(x,par=p)
plot,x,y
RETURNS:
p.a2*x^2 + p.a1*x + p.a0 + p.h * exp( - ((x-p.x0)/2/p.w)^2 )
(See general/tools/fitting/gauss.pro)
FUNCTION: GAUSS
PURPOSE:
Evaluates a gaussian function with background.
This function may be used with the "fit" curve fitting procedure.
KEYWORDS:
PARAMETERS: structure with the format:
** Structure <275ac0>, 6 tags, length=48, refs=1:
a DOUBLE 1.0000000 ; area
s DOUBLE 1.0000000 ; sigma
X0 DOUBLE 0.0000000 ; center
If this parameter is not a structure then it will be created.
USAGE:
x = findgen(100)/10.
y = gaussian(x,par=p)
plot,x,y
RETURNS:
result
(See general/tools/fitting/gauss2.pro)
FUNCTION: GAUSSIAN
PURPOSE:
Evaluates a gaussian function with background.
This function may be used with the "fitfunc" curve fitting function.
KEYWORDS:
PARAMETERS: structure with the format:
** Structure <275ac0>, 6 tags, length=48, refs=1:
H DOUBLE 1.0000000 ; hieght
W DOUBLE 1.0000000 ; width
X0 DOUBLE 0.0000000 ; center
A0 DOUBLE 0.0000000
A1 DOUBLE 0.0000000
A2 DOUBLE 0.0000000
If this parameter is not a structure then it will be created.
P_NAMES: string array (see "fitfunc" for details)
PDER_VALUES: named variable in which partial derivatives are returned.
USAGE:
p={h:2.,w:1.5,x0:5.0,a0:0.,a1:0.,a2:0.}
x = findgen(100)/10.
y = gaussian(x,par=p)
plot,x,y
RETURNS:
p.a2*x^2 + p.a1*x + p.a0 + p.h * exp( - ((x-p.x0)/p.w)^2 )
(See general/tools/fitting/gaussian.pro)
FUNCTION: MGAUSS
PURPOSE:
Evaluates multiple gaussian function with background.
This function may be used with the "fit" curve fitting procedure.
KEYWORDS:
PARAMETERS: a structure that contain the parameters that define the gaussians
If this parameter is not a structure then it will be created.
USAGE:
par = mgauss( numg =4 ) ; get parameter structure with 4 gaussian peaks
x = findgen(100)/10.
y = mgauss(x,param = par)
plot,x,y
RETURNS:
result
Written by: Davin Larson
$LastChangedBy: davin-mac $
$LastChangedDate: 2020-04-04 00:08:25 -0700 (Sat, 04 Apr 2020) $
$LastChangedRevision: 28500 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/tools/fitting/mgauss.pro $
(See general/tools/fitting/mgauss.pro)
FUNCTION polycurve(x,par=p) PURPOSE: Evaluates a (5th degree) polynomial (can be used with "FIT")
(See general/tools/fitting/polycurve.pro)
FUNCTION polycurve2(x,par=p) PURPOSE: Evaluates a (Nth degree) polynomial (can be used with "FIT")
(See general/tools/fitting/polycurve2.pro)
FUNCTION power_law(x,par=p) PURPOSE: Evaluates a power law function (with background) (can be used with "FIT")
(See general/tools/fitting/power_law.pro)
FUNCTION splfunc USAGE: p = splfunc(x_old,y_old,/set) y = splfunc(x_new,param=p)
(See general/tools/fitting/splfunc.pro)
FUNCTION splinef USAGE: y_new = spline_fit3(x_new,x_old,y_old)
(See general/tools/fitting/spline_fit3.pro)