This page was created by the IDL library routine `mk_html_help2`.

Last modified: Fri Jun 10 01:15:43 2011.

# Directory Listing of Routines

# ssl_general/tools/fitting

- EXPONENTIAL
- FIT[1]
  Non-linear least squares fit to a user defined function.
- FIT[2]
  Non-linear least squares fit to a user defined function.
- FIT_CRIB
- GAUSS
  Evaluates a gaussian function with background.
- GAUSS2
  Evaluates a gaussian function with background.
- GAUSSIAN
  Evaluates a gaussian function with background.
- MGAUSS
  Evaluates multiple gaussian function with background.
- POLYCURVE
  Evaluates a (4th degree) polynomial (can be used with "FIT")
- POWER_LAW
  Evaluates a power law function (with background) (can be used with "FIT")
- SPLFUNC

# Routine Descriptions

## EXPONENTIAL

[Next Routine] [List of Routines]

    FUNCTION EXPONENTIAL
    USAGE:
      y = exponential(x,par=p)

(See ssl_general/tools/fitting/exponential.pro)

## FIT[1]

[Previous Routine] [Next Routine] [List of Routines]

     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, P_NAMES=strarray, $
                 FUNCTION_NAME=string, ITMAX=ITMAX, ITER=ITER, TOL=TOL, $
                 /NODERIVATIVE

     INPUTS:
           X:  A row vector of independent variables.  This routine does
         not manipulate or use values in 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.

           SILENT:  If this keyword is set then no fit information is printed.
           MAXPRINT: Maximum number of parameters to display while iterating
                   (Default is 8)

     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 "GAUSSIAN".

       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:
           Copied from "CURFIT", 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"

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

(See ssl_general/tools/fitting/fit.old1.pro)

## FIT[2]

[Previous Routine] [Next Routine] [List of Routines]

     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.

(See ssl_general/tools/fitting/fit.pro)

## FIT_CRIB

[Previous Routine] [Next Routine] [List of Routines]

     Crib sheet to show how to use fit routine.

(See ssl_general/tools/fitting/fit_crib.pro)

## GAUSS

[Previous Routine] [Next Routine] [List of Routines]

    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 ssl_general/tools/fitting/gauss.pro)

## GAUSS2

[Previous Routine] [Next Routine] [List of Routines]

    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 ssl_general/tools/fitting/gauss2.pro)

## GAUSSIAN

[Previous Routine] [Next Routine] [List of Routines]

    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 ssl_general/tools/fitting/gaussian.pro)

## MGAUSS

[Previous Routine] [Next Routine] [List of Routines]

    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-win $
     $LastChangedDate: 2011-03-22 12:29:06 -0700 (Tue, 22 Mar 2011) $
     $LastChangedRevision: 8533 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tools/fitting/mgauss.pro $

(See ssl_general/tools/fitting/mgauss.pro)

## POLYCURVE

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION  polycurve(x,par=p)
    PURPOSE:
       Evaluates a (4th degree) polynomial (can be used with "FIT")

(See ssl_general/tools/fitting/polycurve.pro)

## POWER_LAW

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION  power_law(x,par=p)
    PURPOSE:
       Evaluates a power law function (with background) (can be used with "FIT")

(See ssl_general/tools/fitting/power_law.pro)

## SPLFUNC

[Previous Routine] [List of Routines]

    FUNCTION splfunc
    USAGE:
      p = splfunc(x_old,y_old,/set)
      y = splfunc(x_new,param=p)

(See ssl_general/tools/fitting/splfunc.pro)