org.apache.commons.math.estimation
Class AbstractEstimator

java.lang.Object
  extended by org.apache.commons.math.estimation.AbstractEstimator
All Implemented Interfaces:
Estimator
Direct Known Subclasses:
GaussNewtonEstimator, LevenbergMarquardtEstimator

public abstract class AbstractEstimator
extends java.lang.Object
implements Estimator

Base class for implementing estimators.

This base class handles the boilerplates methods associated to thresholds settings, jacobian and error estimation.

Since:
1.2
Version:
$Revision: 627987 $ $Date: 2008-02-15 03:01:26 -0700 (Fri, 15 Feb 2008) $

Field Summary
protected  int cols
          Number of columns of the jacobian matrix.
protected  double cost
          Cost value (square root of the sum of the residuals).
private  int costEvaluations
          Number of cost evaluations.
protected  double[] jacobian
          Jacobian matrix.
private  int jacobianEvaluations
          Number of jacobian evaluations.
private  int maxCostEval
          Maximal allowed number of cost evaluations.
protected  WeightedMeasurement[] measurements
          Array of measurements.
protected  EstimatedParameter[] parameters
          Array of parameters.
protected  double[] residuals
          Residuals array.
protected  int rows
          Number of rows of the jacobian matrix.
 
Constructor Summary
protected AbstractEstimator()
          Build an abstract estimator for least squares problems.
 
Method Summary
abstract  void estimate(EstimationProblem problem)
          Solve an estimation problem.
 double getChiSquare(EstimationProblem problem)
          Get the Chi-Square value.
 int getCostEvaluations()
          Get the number of cost evaluations.
 double[][] getCovariances(EstimationProblem problem)
          Get the covariance matrix of estimated parameters.
 int getJacobianEvaluations()
          Get the number of jacobian evaluations.
 double getRMS(EstimationProblem problem)
          Get the Root Mean Square value.
 double[] guessParametersErrors(EstimationProblem problem)
          Guess the errors in estimated parameters.
protected  void incrementJacobianEvaluationsCounter()
          Increment the jacobian evaluations counter.
protected  void initializeEstimate(EstimationProblem problem)
          Initialization of the common parts of the estimation.
 void setMaxCostEval(int maxCostEval)
          Set the maximal number of cost evaluations allowed.
protected  void updateJacobian()
          Update the jacobian matrix.
protected  void updateResidualsAndCost()
          Update the residuals array and cost function value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

measurements

protected WeightedMeasurement[] measurements
Array of measurements.


parameters

protected EstimatedParameter[] parameters
Array of parameters.


jacobian

protected double[] jacobian
Jacobian matrix.

This matrix is in canonical form just after the calls to updateJacobian(), but may be modified by the solver in the derived class (the Levenberg-Marquardt estimator does this).


cols

protected int cols
Number of columns of the jacobian matrix.


rows

protected int rows
Number of rows of the jacobian matrix.


residuals

protected double[] residuals
Residuals array.

This array is in canonical form just after the calls to updateJacobian(), but may be modified by the solver in the derived class (the Levenberg-Marquardt estimator does this).


cost

protected double cost
Cost value (square root of the sum of the residuals).


maxCostEval

private int maxCostEval
Maximal allowed number of cost evaluations.


costEvaluations

private int costEvaluations
Number of cost evaluations.


jacobianEvaluations

private int jacobianEvaluations
Number of jacobian evaluations.

Constructor Detail

AbstractEstimator

protected AbstractEstimator()
Build an abstract estimator for least squares problems.

Method Detail

setMaxCostEval

public final void setMaxCostEval(int maxCostEval)
Set the maximal number of cost evaluations allowed.

Parameters:
maxCostEval - maximal number of cost evaluations allowed
See Also:
estimate(org.apache.commons.math.estimation.EstimationProblem)

getCostEvaluations

public final int getCostEvaluations()
Get the number of cost evaluations.

Returns:
number of cost evaluations

getJacobianEvaluations

public final int getJacobianEvaluations()
Get the number of jacobian evaluations.

Returns:
number of jacobian evaluations

updateJacobian

protected void updateJacobian()
Update the jacobian matrix.


incrementJacobianEvaluationsCounter

protected final void incrementJacobianEvaluationsCounter()
Increment the jacobian evaluations counter.


updateResidualsAndCost

protected void updateResidualsAndCost()
                               throws EstimationException
Update the residuals array and cost function value.

Throws:
EstimationException - if the number of cost evaluations exceeds the maximum allowed

getRMS

public double getRMS(EstimationProblem problem)
Get the Root Mean Square value. Get the Root Mean Square value, i.e. the root of the arithmetic mean of the square of all weighted residuals. This is related to the criterion that is minimized by the estimator as follows: if c if the criterion, and n is the number of measurements, then the RMS is sqrt (c/n).

Specified by:
getRMS in interface Estimator
Parameters:
problem - estimation problem
Returns:
RMS value
See Also:
Estimator.guessParametersErrors(EstimationProblem)

getChiSquare

public double getChiSquare(EstimationProblem problem)
Get the Chi-Square value.

Parameters:
problem - estimation problem
Returns:
chi-square value

getCovariances

public double[][] getCovariances(EstimationProblem problem)
                          throws EstimationException
Get the covariance matrix of estimated parameters.

Specified by:
getCovariances in interface Estimator
Parameters:
problem - estimation problem
Returns:
covariance matrix
Throws:
EstimationException - if the covariance matrix cannot be computed (singular problem)

guessParametersErrors

public double[] guessParametersErrors(EstimationProblem problem)
                               throws EstimationException
Guess the errors in estimated parameters.

Guessing is covariance-based, it only gives rough order of magnitude.

Specified by:
guessParametersErrors in interface Estimator
Parameters:
problem - estimation problem
Returns:
errors in estimated parameters
Throws:
EstimationException - if the covariances matrix cannot be computed or the number of degrees of freedom is not positive (number of measurements lesser or equal to number of parameters)
See Also:
Estimator.getRMS(EstimationProblem)

initializeEstimate

protected void initializeEstimate(EstimationProblem problem)
Initialization of the common parts of the estimation.

This method must be called at the start of the estimate method.

Parameters:
problem - estimation problem to solve

estimate

public abstract void estimate(EstimationProblem problem)
                       throws EstimationException
Solve an estimation problem.

The method should set the parameters of the problem to several trial values until it reaches convergence. If this method returns normally (i.e. without throwing an exception), then the best estimate of the parameters can be retrieved from the problem itself, through the EstimationProblem.getAllParameters method.

Specified by:
estimate in interface Estimator
Parameters:
problem - estimation problem to solve
Throws:
EstimationException - if the problem cannot be solved