Module ij
Package ij.measure

Class CurveFitter

java.lang.Object
ij.measure.CurveFitter
All Implemented Interfaces:
UserFunction

public class CurveFitter
extends java.lang.Object
implements UserFunction
Curve fitting class based on the Simplex method in the Minimizer class Notes on fitting polynomial functions: (i) The range of x values should not be too far from 0, especially for higher-order polynomials. For polynomials of 4th order, the average x value should fulfill |xMean|
  • Field Summary

    Fields 
    Modifier and Type Field Description
    static int CHAPMAN
    Constants for the built-in fit functions
    static int ERF
    Constants for the built-in fit functions
    static int EXP_RECOVERY
    Constants for the built-in fit functions
    static int EXP_RECOVERY_NOOFFSET
    Constants for the built-in fit functions
    static int EXP_REGRESSION
    Constants for the built-in fit functions
    static int EXP_WITH_OFFSET
    Constants for the built-in fit functions
    static int EXPONENTIAL
    Constants for the built-in fit functions
    static java.lang.String[] fitList
    Names of the built-in fit functions
    static java.lang.String[] fList
    Equations of the built-in fit functions
    static java.lang.String[] fMacro
    ImageJ Macro language code for the built-in functions
    static int GAMMA_VARIATE
    Constants for the built-in fit functions
    static int GAUSSIAN
    Constants for the built-in fit functions
    static int GAUSSIAN_NOOFFSET
    Constants for the built-in fit functions
    static int INV_RODBARD
    Constants for the built-in fit functions
    static int IterFactor
    Deprecated.
    now in the Minimizer class (since ImageJ 1.46f).
    static int LOG
    Constants for the built-in fit functions
    static int LOG2
    Constants for the built-in fit functions
    static int POLY2
    Constants for the built-in fit functions
    static int POLY3
    Constants for the built-in fit functions
    static int POLY4
    Constants for the built-in fit functions
    static int POLY5
    Constants for the built-in fit functions
    static int POLY6
    Constants for the built-in fit functions
    static int POLY7
    Constants for the built-in fit functions
    static int POLY8
    Constants for the built-in fit functions
    static int POWER
    Constants for the built-in fit functions
    static int POWER_REGRESSION
    Constants for the built-in fit functions
    static int RODBARD
    Constants for the built-in fit functions
    static int RODBARD2
    Constants for the built-in fit functions
    static int[] sortedTypes
    Nicer sequence of the built-in function types
    static int STRAIGHT_LINE
    Constants for the built-in fit functions
  • Constructor Summary

    Constructors 
    Constructor Description
    CurveFitter​(double[] xData, double[] yData)
    Construct a new CurveFitter.
  • Method Summary

    Modifier and Type Method Description
    void doCustomFit​(UserFunction userFunction, int numParams, java.lang.String formula, double[] initialParams, double[] initialParamVariations, boolean showSettings)
    Fit a function defined in a user plugin implementing the UserFunction interface Use getStatus() and/or getStatusString() to see whether fitting was (probably) successful and getParams() to access the result.
    int doCustomFit​(java.lang.String equation, double[] initialParams, boolean showSettings)
    Fit a function defined as a macro String like "y = a + b*x + c*x*x".
    void doFit​(int fitType)
    Perform curve fitting with one of the built-in functions doFit(fitType) does the fit quietly Use getStatus() and/or getStatusString() to see whether fitting was (probably) successful and getParams() to access the result.
    void doFit​(int fitType, boolean showSettings)
    Perform curve fitting with one of the built-in functions doFit(fitType, true) pops up a dialog allowing the user to set the initial fit parameters and various numbers controlling the Minimizer Use getStatus() and/or getStatusString() to see whether fitting was (probably) successful and getParams() to access the result.
    double f​(double x)
    Returns the formula value for parameters 'p' at 'x'.
    double f​(double[] p, double x)
    Returns the formula value for parameters 'p' at 'x'.
    static double f​(int fitType, double[] p, double x)
    Returns value of built-in 'fitType' formula value for parameters "p" at "x"
    int getFit()
    returns the code of the fit type of the fit performed
    static int getFitCode​(java.lang.String fitName)
    Returns the code for a fit with given name as defined in fitList, or -1 if not found
    double getFitGoodness()
    Get a measure of "goodness of fit" where 1.0 is best.
    java.lang.String getFormula()
    returns a String with the formula of the fit function used
    int getIterations()
    Get number of iterations performed.
    java.lang.String getMacroCode()
    Returns macro code of the form "y = ...x" for the fit function used.
    static int getMax​(double[] array)
    Gets index of highest value in an array.
    int getMaxIterations()
    Get maximum number of iterations allowed (sum of iteration count for all restarts)
    Minimizer getMinimizer()
    Returns a reference to the Minimizer used, for accessing Minimizer methods directly.
    java.lang.String getName()
    returns the name of the fit function of the fit performed
    int getNumParams()
    Get number of parameters for current fit formula Do not use before 'doFit', because the fit function would be undefined.
    static int getNumParams​(int fitType)
    Returns the number of parameters for a given fit type, except for the 'custom' fit, where the number of parameters is given by the equation: see getNumParams(String)
    static int getNumParams​(java.lang.String customFormula)
    Returns the number of parameters for a custom equation given as a macro String, like "y = a + b*x + c*x*x" .
    double[] getParams()
    Get the result of fitting, i.e.
    Plot getPlot()  
    Plot getPlot​(int points)  
    double[] getResiduals()
    Returns residuals array, i.e., differences between data and curve.
    int getRestarts()
    Get maximum number of simplex restarts to do.
    java.lang.String getResultString()
    Get a string with detailed description of the curve fitting results (several lines, including the fit parameters).
    double getRSquared()
    Returns R^2, where 1.0 is best.
    double getSD()
    Returns the standard deviation of the residuals.
    static java.lang.String[] getSortedFitList()
    Returns an array of fit names with nicer sorting
    int getStatus()  
    java.lang.String getStatusString()
    Get a short text with a short description of the status.
    double getSumResidualsSqr()  
    double[] getXPoints()
    returns the array with the x data
    double[] getYPoints()
    returns the array with the y data
    void setInitialParameters​(double[] initialParams)
    Sets the initial parameters, which override the default initial parameters.
    void setMaxError​(double maxRelError)
    Set the maximum error.
    void setMaxIterations​(int maxIter)
    Set maximum number of iterations allowed (sum of iteration count for all restarts)
    void setOffsetMultiplySlopeParams​(int offsetParam, int multiplyParam, int slopeParam)
    For improved fitting performance when using a custom fit formula, one may specify parameters that can be calculated directly by linear regression.
    void setRestarts​(int maxRestarts)
    Set maximum number of simplex restarts to do.
    void setStatusAndEsc​(java.lang.String ijStatusString, boolean checkEscape)
    Create output on the number of iterations in the ImageJ Status line, e.g.
    double userFunction​(double[] params, double dummy)
    This function is called by the Minimizer and calculates the sum of squared residuals for given parameters.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

  • Constructor Details

    • CurveFitter

      public CurveFitter​(double[] xData, double[] yData)
      Construct a new CurveFitter.
  • Method Details

    • doFit

      public void doFit​(int fitType)
      Perform curve fitting with one of the built-in functions doFit(fitType) does the fit quietly Use getStatus() and/or getStatusString() to see whether fitting was (probably) successful and getParams() to access the result.
    • doFit

      public void doFit​(int fitType, boolean showSettings)
      Perform curve fitting with one of the built-in functions doFit(fitType, true) pops up a dialog allowing the user to set the initial fit parameters and various numbers controlling the Minimizer Use getStatus() and/or getStatusString() to see whether fitting was (probably) successful and getParams() to access the result.
    • doCustomFit

      public int doCustomFit​(java.lang.String equation, double[] initialParams, boolean showSettings)
      Fit a function defined as a macro String like "y = a + b*x + c*x*x". Returns the number of parameters, or 0 in case of a macro syntax error. For good performance, it is advisable to set also the typical variation range of the initial parameters by the getMinimizer().setInitialParamVariations(double[]) method (especially if one or more of the initialParams are zero). Use getStatus() and/or getStatusString() to see whether fitting was (probably) successful and getParams() to access the result.
    • doCustomFit

      public void doCustomFit​(UserFunction userFunction, int numParams, java.lang.String formula, double[] initialParams, double[] initialParamVariations, boolean showSettings)
      Fit a function defined in a user plugin implementing the UserFunction interface Use getStatus() and/or getStatusString() to see whether fitting was (probably) successful and getParams() to access the result.
      Parameters:
      userFunction - A plugin where the fit function is defined by the userFunction(params, x) method. This function must allow simultaneous calls in multiple threads.
      numParams - Number of parameters of the fit function.
      formula - A String describing the fit formula, may be null.
      initialParams - Starting point for the parameters; may be null (than values of 0 are used). The fit function with these parameters must not return NaN for any of the data points given in the constructor (xData).
      initialParamVariations - Each parameter is initially varied by up to +/- this value. If not given (null), initial variations are taken as 10% of initial parameter value or 0.01 for parameters that are zero. When this array is given, all elements must be positive (nonzero). See Minimizer.minimize for details.
      showSettings - Displays a popup dialog for modifying the initial parameters and a few numbers controlling the minimizer.
    • setInitialParameters

      public void setInitialParameters​(double[] initialParams)
      Sets the initial parameters, which override the default initial parameters.
    • getMinimizer

      public Minimizer getMinimizer()
      Returns a reference to the Minimizer used, for accessing Minimizer methods directly. Note that no Minimizer is used if fitType is any of STRAIGHT_LINE, EXP_REGRESSION, and POWER_REGRESSION.
    • setOffsetMultiplySlopeParams

      public void setOffsetMultiplySlopeParams​(int offsetParam, int multiplyParam, int slopeParam)
      For improved fitting performance when using a custom fit formula, one may specify parameters that can be calculated directly by linear regression. For values not used, set the index to -1
      Parameters:
      offsetParam - Index of a parameter that is a pure offset: E.g. '0' if f(p0, p1, p2...) = p0 + function(p1, p2, ...).
      multiplyParam - Index of a parameter that is purely multiplicative. E.g. multiplyParams=1 if f(p0, p1, p2, p3...) can be expressed as p1*func(p0, p2, p3, ...) or p0 +p1*func(p0, p2, p3, ...) with '0' being the offsetparam.
      slopeParam - Index of a parameter that is multiplied with x and then summed to the function. E.g. '1' for f(p0, p1, p2, p3...) = p1*x + func(p0, p2, p3, ...) Only one, multiplyParam and slopeParam can be used (ie.e, the other should be set to -1)
    • getNumParams

      public int getNumParams()
      Get number of parameters for current fit formula Do not use before 'doFit', because the fit function would be undefined.
    • getNumParams

      public static int getNumParams​(int fitType)
      Returns the number of parameters for a given fit type, except for the 'custom' fit, where the number of parameters is given by the equation: see getNumParams(String)
    • getNumParams

      public static int getNumParams​(java.lang.String customFormula)
      Returns the number of parameters for a custom equation given as a macro String, like "y = a + b*x + c*x*x" . Restricted to 6 parameters "a" ... "f" (fitting more parameters is not likely to yield an accurate result anyhow). Returns 0 if a very basic check does not find a formula of this type.
    • f

      public final double f​(double x)
      Returns the formula value for parameters 'p' at 'x'. Do not use before 'doFit', because the fit function would be undefined.
    • f

      public final double f​(double[] p, double x)
      Returns the formula value for parameters 'p' at 'x'. Do not use before 'doFit', because the fit function would be undefined.
    • f

      public static double f​(int fitType, double[] p, double x)
      Returns value of built-in 'fitType' formula value for parameters "p" at "x"
    • getParams

      public double[] getParams()
      Get the result of fitting, i.e. the set of parameter values for the best fit. Note that the array returned may have more elements than numParams; ignore the rest. May return an array with only NaN values if the minimizer could not start properly, i.e., if getStatus() returns Minimizer.INITILIZATION_FAILURE. See Minimizer.getParams() for details.
    • getResiduals

      public double[] getResiduals()
      Returns residuals array, i.e., differences between data and curve. The residuals are with respect to the real data, also for fit types where the data are modified before fitting (power&exp fit by linear regression, 'Rodbard NIH Image' ). This is in contrast to sum of squared residuals, which is for the fit that was actually done.
    • getSumResidualsSqr

      public double getSumResidualsSqr()
    • getSD

      public double getSD()
      Returns the standard deviation of the residuals. Here, the standard deviation is defined here as the root-mean-square of the residuals times sqrt(n/(n-1)); where n is the number of points.
    • getRSquared

      public double getRSquared()
      Returns R^2, where 1.0 is best.
               r^2 = 1 - SSE/SSD
      
               where:  SSE = sum of the squared errors
                                       SSD = sum of the squared deviations about the mean.
              
      For power, exp by linear regression and 'Rodbard NIH Image', this is calculated for the fit actually done, not for the residuals of the original data.
    • getFitGoodness

      public double getFitGoodness()
      Get a measure of "goodness of fit" where 1.0 is best. Approaches R^2 if the number of points is much larger than the number of fit parameters. For power, exp by linear regression and 'Rodbard NIH Image', this is calculated for the fit actually done, not for the residuals of the original data.
    • getStatus

      public int getStatus()
    • getStatusString

      public java.lang.String getStatusString()
      Get a short text with a short description of the status. Should be preferred over Minimizer.STATUS_STRING[getMinimizer().getStatus()] because getStatusString() better explains the problem in some cases of initialization failure (data not compatible with the fit function chosen)
    • getResultString

      public java.lang.String getResultString()
      Get a string with detailed description of the curve fitting results (several lines, including the fit parameters).
    • setRestarts

      public void setRestarts​(int maxRestarts)
      Set maximum number of simplex restarts to do. See Minimizer.setMaxRestarts for details.
    • setMaxError

      public void setMaxError​(double maxRelError)
      Set the maximum error. by which the sum of residuals may deviate from the true value (relative w.r.t. full sum of rediduals). Possible range: 0.1 ... 10^-16
    • setStatusAndEsc

      public void setStatusAndEsc​(java.lang.String ijStatusString, boolean checkEscape)
      Create output on the number of iterations in the ImageJ Status line, e.g. " 50 (max 750); ESC to stop"
      Parameters:
      ijStatusString - Displayed in the beginning of the status message. No display if null. E.g. "Curve Fit: Iteration "
      checkEscape - When true, the Minimizer stops if escape is pressed and the status becomes ABORTED. Note that checking for ESC does not work in the Event Queue thread.
    • getIterations

      public int getIterations()
      Get number of iterations performed. Returns 1 in case the fit was done by linear regression only.
    • getMaxIterations

      public int getMaxIterations()
      Get maximum number of iterations allowed (sum of iteration count for all restarts)
    • setMaxIterations

      public void setMaxIterations​(int maxIter)
      Set maximum number of iterations allowed (sum of iteration count for all restarts)
    • getRestarts

      public int getRestarts()
      Get maximum number of simplex restarts to do. See Minimizer.setMaxRestarts for details.
    • getXPoints

      public double[] getXPoints()
      returns the array with the x data
    • getYPoints

      public double[] getYPoints()
      returns the array with the y data
    • getFit

      public int getFit()
      returns the code of the fit type of the fit performed
    • getName

      public java.lang.String getName()
      returns the name of the fit function of the fit performed
    • getFormula

      public java.lang.String getFormula()
      returns a String with the formula of the fit function used
    • getMacroCode

      public java.lang.String getMacroCode()
      Returns macro code of the form "y = ...x" for the fit function used. Note that this is not neccessarily the equation acutally used for the fit (for the various "linear regression" types and RODBARD2, the fit is done differently). Note that no macro code may be avialable for custom fits using the UserFunction interface.
    • getSortedFitList

      public static java.lang.String[] getSortedFitList()
      Returns an array of fit names with nicer sorting
    • getFitCode

      public static int getFitCode​(java.lang.String fitName)
      Returns the code for a fit with given name as defined in fitList, or -1 if not found
    • userFunction

      public final double userFunction​(double[] params, double dummy)
      This function is called by the Minimizer and calculates the sum of squared residuals for given parameters. To improve the efficiency, simple linear dependencies are solved directly by linear regression; in that case the corresponding parameters are modified. This effectively reduces the number of free parameters by one or two and thereby significantly improves the performance of minimization.
      Specified by:
      userFunction in interface UserFunction
      Parameters:
      params - When minimizing, array of variables. For curve fit array of fit parameters. The array contents should not be modified. Note that the function can get an array with more elements then needed to specify the parameters. Ignore the rest (and don't modify them).
      dummy - For a fit function, the independent variable of the function. Ignore it when using the minimizer.
      Returns:
      The result of the function.
    • getMax

      public static int getMax​(double[] array)
      Gets index of highest value in an array.
      Parameters:
      array - the array.
      Returns:
      Index of highest value.
    • getPlot

      public Plot getPlot()
    • getPlot

      public Plot getPlot​(int points)