Package com.irurueta.numerical.fitting

Class LevenbergMarquardtMultiVariateFitter

java.lang.Object
com.irurueta.numerical.fitting.Fitter
com.irurueta.numerical.fitting.MultiVariateFitter
com.irurueta.numerical.fitting.LevenbergMarquardtMultiVariateFitter
public class LevenbergMarquardtMultiVariateFitter extends MultiVariateFitter
Fits provided data (x, y) to a generic non-linear function using Levenberg-Marquardt iterative algorithm. This class is based on the implementation available at Numerical Recipes 3rd Ed, page 801.

  • Field Details

    • DEFAULT_NDONE

      public static final int DEFAULT_NDONE
      Default convergence parameter. Number of times that tolerance is assumed to be reached to consider that algorithm has finished iterating.
      See Also:

    • DEFAULT_ITMAX

      public static final int DEFAULT_ITMAX
      Default maximum number of iterations.
      See Also:

    • DEFAULT_TOL

      public static final double DEFAULT_TOL
      Default tolerance to reach convergence.
      See Also:

    • DEFAULT_ADJUST_COVARIANCE

      public static final boolean DEFAULT_ADJUST_COVARIANCE
      Indicates whether covariance must be adjusted or not after fitting is finished.
      See Also:

    • ndone

      private int ndone
      Convergence parameter.

    • itmax

      private int itmax
      Maximum number of iterations.

    • tol

      private double tol
      Tolerance to reach convergence.

    • evaluator

      private LevenbergMarquardtMultiVariateFunctionEvaluator evaluator
      Evaluator of functions.

    • ma

      private int ma
      Number of function parameters to be estimated.

    • ia

      private boolean[] ia
      Determines which parameters can be modified during estimation (if true) and which ones are locked (if false).

    • alpha

      private com.irurueta.algebra.Matrix alpha
      Curvature matrix.

    • mfit

      private int mfit
      Number of parameters ot be fitted.

    • xRow

      private double[] xRow
      An input point to be evaluated.

    • ymod

      private double[] ymod
      Results of function evaluations.

    • jacobian

      com.irurueta.algebra.Matrix jacobian
      Jacobian of function at a given point.

    • mse

      private double mse
      Mean square error.

    • adjustCovariance

      private boolean adjustCovariance
      Indicates whether covariance must be adjusted or not. When covariance adjustment is enabled, then covariance is recomputed taking into account input samples, input standard deviations of the samples and jacobians of the model function overestimated parameters using the following expression: Cov = (J'*W*J)^-1 where: Cov is the covariance of estimated parameters J is a matrix containing the Jacobians of the function overestimated parameters for each input parameter x. Each row of J matrix contains an evaluation of the model function Jacobian for i-th input parameter x. Each column of J matrix contains the partial derivative of model function over j-th estimated parameter. W is the inverse of input variances. It's a diagonal matrix containing the reciprocal of the input variances (squared input standard deviations). That is: W = diag(w) where k element of w is wk = 1 / sigmak^2, which corresponds to the k-th standard deviation of input sample k. By default, covariance is adjusted after fitting finishes.

  • Constructor Details

    • LevenbergMarquardtMultiVariateFitter

      public LevenbergMarquardtMultiVariateFitter()
      Constructor.

    • LevenbergMarquardtMultiVariateFitter

      public LevenbergMarquardtMultiVariateFitter(com.irurueta.algebra.Matrix x, com.irurueta.algebra.Matrix y, double[] sig)
      Constructor.
      Parameters:
      x - input points x where multivariate function f(x1, x2, ...) is evaluated.
      y - result of evaluation of linear single dimensional function f(x) at provided multidimensional x points.
      sig - standard deviations of each pair of points (x, y).
      Throws:
      IllegalArgumentException - if provided number of rows and arrays don't have the same length.

    • LevenbergMarquardtMultiVariateFitter

      public LevenbergMarquardtMultiVariateFitter(com.irurueta.algebra.Matrix x, com.irurueta.algebra.Matrix y, double sig)
      Constructor.
      Parameters:
      x - input points x where multivariate function f(x1, x2, ...) is evaluated.
      y - result of evaluation of linear single dimensional function f(x) at provided multidimensional x points.
      sig - standard deviation of all pair of points assuming that standard deviations are constant.
      Throws:
      IllegalArgumentException - if provided number of rows and arrays don't have the same length.

    • LevenbergMarquardtMultiVariateFitter

      public LevenbergMarquardtMultiVariateFitter(LevenbergMarquardtMultiVariateFunctionEvaluator evaluator) throws FittingException
      Constructor.
      Parameters:
      evaluator - evaluator to evaluate function at provided point and obtain the evaluation of function basis at such point.
      Throws:
      FittingException - if evaluation fails.

    • LevenbergMarquardtMultiVariateFitter

      public LevenbergMarquardtMultiVariateFitter(LevenbergMarquardtMultiVariateFunctionEvaluator evaluator, com.irurueta.algebra.Matrix x, com.irurueta.algebra.Matrix y, double[] sig) throws FittingException
      Constructor.
      Parameters:
      evaluator - evaluator to evaluate multivariate function at provided point and obtain the evaluation of function basis at such point.
      x - input points x where multivariate function f(x1, x2, ...) is evaluated.
      y - result of evaluation of linear single dimensional function f(x) at provided multidimensional x points.
      sig - standard deviations of each pair of points (x, y).
      Throws:
      IllegalArgumentException - if provided number of rows and arrays don't have the same length.
      FittingException - if evaluation fails.

    • LevenbergMarquardtMultiVariateFitter

      public LevenbergMarquardtMultiVariateFitter(LevenbergMarquardtMultiVariateFunctionEvaluator evaluator, com.irurueta.algebra.Matrix x, com.irurueta.algebra.Matrix y, double sig) throws FittingException
      Constructor.
      Parameters:
      evaluator - evaluator to evaluate multivariate function at provided point and obtain the evaluation of function basis at such point.
      x - input points x where multivariate function f(x1, x2, ...) is evaluated.
      y - result of evaluation of linear single dimensional function f(x) at provided multidimensional x points.
      sig - standard deviation of all pair of points assuming that standard deviations are constant.
      Throws:
      IllegalArgumentException - if provided number of rows and arrays don't have the same length.
      FittingException - if evaluation fails.

  • Method Details

    • getNdone

      public int getNdone()
      Returns convergence parameter.
      Returns:
      convergence parameter.

    • setNdone

      public void setNdone(int ndone)
      Sets convergence parameter.
      Parameters:
      ndone - convergence parameter.
      Throws:
      IllegalArgumentException - if provided value is less than 1.

    • getItmax

      public int getItmax()
      Returns maximum number of iterations.
      Returns:
      maximum number of iterations.

    • setItmax

      public void setItmax(int itmax)
      Sets maximum number of iterations.
      Parameters:
      itmax - maximum number of iterations.
      Throws:
      IllegalArgumentException - if provided value is zero or negative.

    • getTol

      public double getTol()
      Returns tolerance to reach convergence.
      Returns:
      tolerance to reach convergence.

    • setTol

      public void setTol(double tol)
      Sets tolerance to reach convergence.
      Parameters:
      tol - tolerance to reach convergence.
      Throws:
      IllegalArgumentException - if provided value is zero or negative.

    • getFunctionEvaluator

      public LevenbergMarquardtMultiVariateFunctionEvaluator getFunctionEvaluator()
      Returns function evaluator to evaluate function at a given point and obtain function jacobian respect to each provided parameter.
      Returns:
      function evaluator.

    • setFunctionEvaluator

      public final void setFunctionEvaluator(LevenbergMarquardtMultiVariateFunctionEvaluator evaluator) throws FittingException
      Sets function evaluator to evaluate function at a given point and obtain function jacobian respect to each provided parameter.
      Parameters:
      evaluator - function evaluator.
      Throws:
      FittingException - if evaluation fails.

    • isReady

      public boolean isReady()
      Indicates whether provided instance has enough data to start the function fitting.
      Specified by:
      isReady in class Fitter
      Returns:
      true if this instance is ready to start the function fitting, false otherwise.

    • getAlpha

      public com.irurueta.algebra.Matrix getAlpha()
      Returns curvature matrix.
      Returns:
      curvature matrix.

    • getChisqDegreesOfFreedom

      public int getChisqDegreesOfFreedom()
      Returns degrees of freedom of computed chi square value. Degrees of freedom is equal to the number of sampled data minus the number of estimated parameters.
      Returns:
      degrees of freedom of computed chi square value.

    • getMse

      public double getMse()
      Gets mean square error produced by estimated parameters respect to provided sample data.
      Returns:
      mean square error.

    • getP

      public double getP() throws com.irurueta.statistics.MaxIterationsExceededException
      Gets the probability of finding a smaller chi square value. The smaller the found chi square value is, the better the fit of the estimated parameters to the actual parameter. Thus, the smaller the chance of finding a smaller chi square value, then the better the estimated fit is.
      Returns:
      probability of finding a smaller chi square value (better fit), expressed as a value between 0.0 and 1.0.
      Throws:
      com.irurueta.statistics.MaxIterationsExceededException - if convergence of incomplete gamma function cannot be reached. This is rarely thrown and happens usually for numerically unstable input values.

    • getQ

      public double getQ() throws com.irurueta.statistics.MaxIterationsExceededException
      Gets a measure of quality of estimated fit as a value between 0.0 and 1.0. The larger the quality value is, the better the fit that has been estimated.
      Returns:
      measure of quality of estimated fit.
      Throws:
      com.irurueta.statistics.MaxIterationsExceededException - if convergence of incomplete gamma function cannot be reached. This is rarely thrown and happens usually for numerically unstable input values.

    • isCovarianceAdjusted

      public boolean isCovarianceAdjusted()
      Indicates whether covariance must be adjusted or not. When covariance adjustment is enabled, then covariance is recomputed taking into account input samples, input standard deviations of the samples and jacobians of the model function overestimated parameters using the following expression: Cov = (J'*W*J)^-1 where: Cov is the covariance of estimated parameters J is a matrix containing the Jacobians of the function overestimated parameters for each input parameter x. Each row of J matrix contains an evaluation of the model function Jacobian for i-th input parameter x. Each column of J matrix contains the partial derivative of model function over j-th estimated parameter. W is the inverse of input variances. It's a diagonal matrix containing the reciprocal of the input variances (squared input standard deviations). That is: W = diag(w) where k element of w is wk = 1 / sigmak^2, which corresponds to the k-th standard deviation of input sample k. By default, covariance is adjusted after fitting finishes. http://people.duke.edu/~hpgavin/ce281/lm.pdf https://www8.cs.umu.se/kurser/5DA001/HT07/lectures/lsq-handouts.pdf Numerical Recipes 3rd Ed, page 812
      Returns:
      true if covariance must be adjusted, false otherwise.

    • setCovarianceAdjusted

      public void setCovarianceAdjusted(boolean adjustCovariance)
      Specifies whether covariance must be adjusted or not. When covariance adjustment is enabled, then covariance is recomputed taking into account input samples, input standard deviations of the samples and jacobians of the model function overestimated parameters using the following expression: Cov = (J'*W*J)^-1 where: Cov is the covariance of estimated parameters J is a matrix containing the Jacobians of the function overestimated parameters for each input parameter x. Each row of J matrix contains an evaluation of the model function Jacobian for i-th input parameter x. Each column of J matrix contains the partial derivative of model function over j-th estimated parameter. W is the inverse of input variances. It's a diagonal matrix containing the reciprocal of the input variances (squared input standard deviations). That is: W = diag(w) where k element of w is wk = 1 / sigmak^2, which corresponds to the k-th standard deviation of input sample k. By default, covariance is adjusted after fitting finishes.
      Parameters:
      adjustCovariance - true if covariance must be adjusted, false otherwise.

    • fit

      public void fit() throws FittingException, NotReadyException
      Fits a function to provided data so that parameters associated to that function can be estimated along with their covariance matrix and chi square value. If chi square value is close to 1, the fit is usually good. If it is much larger, then error cannot be properly fitted. If it is close to zero, then the model over-fits the error. Methods getP() and getQ() can also be used to determine the quality of the fit.
      Specified by:
      fit in class Fitter
      Throws:
      FittingException - if fitting fails.
      NotReadyException - if enough input data has not yet been provided.

    • hold

      public void hold(int i, double val)
      Prevents parameter at position i of linear combination of basis functions to be modified during function fitting.
      Parameters:
      i - position of parameter to be retained.
      val - value to be set for parameter at position i.

    • free

      public void free(int i)
      Releases parameter at position i of linear combination of basis functions, so it can be modified again if needed.
      Parameters:
      i - position of parameter to be released.

    • adjustCovariance

      private void adjustCovariance() throws com.irurueta.algebra.AlgebraException, EvaluationException
      Adjusts covariance. Covariance must be adjusted to produce more real results close to the scale of problem, otherwise estimated covariance will just be a measure of goodness similar to chi square value because it will be the inverse of the curvature matrix, which is just a solution of the covariance up to scale.

      Covariance is adjusted taking into account input samples, input standard deviations of the samples and jacobians of the model function overestimated parameters using the following expression: Cov = (J'*W*J)^-1 where: Cov is the covariance of estimated parameters J is a matrix containing the Jacobians of the function overestimated parameters for each input parameter x. Each row of J matrix contains an evaluation of the model function Jacobian for i-th input parameter x. Each column of J matrix contains the partial derivative of model function over j-th estimated parameter. W is the inverse of input variances. It's a diagonal matrix containing the reciprocal of the input variances (squared input standard deviations). That is: W = diag(w) where k element of w is wk = 1 / sigmak^2, which corresponds to the k-th standard deviation of input sample k.

      Throws:
      com.irurueta.algebra.AlgebraException - if there are numerical instabilities.
      EvaluationException - if function evaluation fails.

    • internalSetFunctionEvaluator

      private void internalSetFunctionEvaluator(LevenbergMarquardtMultiVariateFunctionEvaluator evaluator) throws FittingException
      Internal method to set function evaluator to evaluate function at a given point and obtain function jacobian respect to each provided parameter.
      Parameters:
      evaluator - function evaluator.
      Throws:
      FittingException - if evaluation fails.

    • mrqcof

      private void mrqcof(double[] a, com.irurueta.algebra.Matrix alpha, double[] beta) throws com.irurueta.algebra.AlgebraException, EvaluationException
      Used by fit to evaluate the linearized fitting matrix alpha, and vector beta to calculate chi square.
      Parameters:
      a - estimated parameters so far.
      alpha - curvature (i.e. fitting) matrix.
      beta - array where derivative increments for each parameter are stored.
      Throws:
      com.irurueta.algebra.AlgebraException - if there are numerical instabilities.
      EvaluationException - if function evaluation fails.

    • covsrt

      private void covsrt(com.irurueta.algebra.Matrix covar)
      Expand in storage the covariance matrix covar, to take into account parameters that are being held fixed. (For the latter, return zero covariances).
      Parameters:
      covar - covariance matrix.

    • swap

      private static void swap(double[] array1, double[] array2, int pos1, int pos2)
      Swaps values of arrays at provided positions.
      Parameters:
      array1 - 1st array.
      array2 - 2nd array.
      pos1 - 1st position.
      pos2 - 2nd position.