Package com.irurueta.numerical.polynomials.estimators

Class PolynomialRobustEstimator

java.lang.Object
com.irurueta.numerical.polynomials.estimators.PolynomialRobustEstimator
Direct Known Subclasses:
LMedSPolynomialRobustEstimator, MSACPolynomialRobustEstimator, PROMedSPolynomialRobustEstimator, PROSACPolynomialRobustEstimator, RANSACPolynomialRobustEstimator
public abstract class PolynomialRobustEstimator extends Object
This is an abstract class for algorithms to robustly find the best Polynomial for provided collection of evaluations. Implementations of this class should be able to detect and discard outliers in order to find the best solution.

  • Field Details

    • DEFAULT_ROBUST_METHOD

      public static final RobustEstimatorMethod DEFAULT_ROBUST_METHOD
      Default robust estimator method when none is provided. In general for Polynomial estimation is best to use PROSAC or RANSAC than any other method, as it provides more robust methods.

    • DEFAULT_PROGRESS_DELTA

      public static final float DEFAULT_PROGRESS_DELTA
      Default amount of progress variation before notifying a change in estimation progress. By default, this is set to 5%.
      See Also:

    • MIN_PROGRESS_DELTA

      public static final float MIN_PROGRESS_DELTA
      Minimum allowed value for progress delta.
      See Also:

    • MAX_PROGRESS_DELTA

      public static final float MAX_PROGRESS_DELTA
      Maximum allowed value for progress delta.
      See Also:

    • DEFAULT_CONFIDENCE

      public static final double DEFAULT_CONFIDENCE
      Constant defining default confidence of the estimated result, which is 99%. This means that with a probability of 99% estimation will be accurate because chosen sub-samples will be inliers.
      See Also:

    • DEFAULT_MAX_ITERATIONS

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

    • MIN_CONFIDENCE

      public static final double MIN_CONFIDENCE
      Minimum allowed confidence value.
      See Also:

    • MAX_CONFIDENCE

      public static final double MAX_CONFIDENCE
      Maximum allowed confidence value.
      See Also:

    • MIN_ITERATIONS

      public static final int MIN_ITERATIONS
      Minimum allowed number of iterations.
      See Also:

    • DEFAULT_USE_GEOMETRIC_DISTANCE

      public static final boolean DEFAULT_USE_GEOMETRIC_DISTANCE
      Flag indicating whether geometric distance is used by default or not to find outliers.
      See Also:

    • evaluations

      protected List<PolynomialEvaluation> evaluations
      Collection of polynomial evaluations and their corresponding point of evaluation used to determine a polynomial of required degree.

    • polynomialEstimator

      protected final LMSEPolynomialEstimator polynomialEstimator
      Internal non robust estimator of polynomial estimator.

    • listener

      protected PolynomialRobustEstimatorListener listener
      Listener to be notified of events such as when estimation starts, ends or its progress significantly changes.

    • locked

      protected boolean locked
      Indicates if this estimator is locked because an estimation is being computed.

    • progressDelta

      protected float progressDelta
      Amount of progress variation before notifying a progress change during estimation.

    • confidence

      protected double confidence
      Amount of confidence expressed as a value between 0.0 and 1.0 (which is equivalent to 100%). The amount of confidence indicates the probability that the estimated result is correct. Usually this value will be close to 1.0, but not exactly 1.0.

    • maxIterations

      protected int maxIterations
      Maximum allowed number of iterations. When the maximum number of iterations is exceeded, result will not be available, however an approximate result will be available for retrieval.

    • useGeometricDistance

      protected boolean useGeometricDistance
      Indicates whether geometric distance will be used to find outliers or algebraic distance will be used instead.

  • Constructor Details

    • PolynomialRobustEstimator

      protected PolynomialRobustEstimator()
      Constructor.

    • PolynomialRobustEstimator

      protected PolynomialRobustEstimator(int degree)
      Constructor.
      Parameters:
      degree - degree of polynomial to be estimated.
      Throws:
      IllegalArgumentException - if provided degree is less than 1.

    • PolynomialRobustEstimator

      protected PolynomialRobustEstimator(List<PolynomialEvaluation> evaluations)
      Constructor.
      Parameters:
      evaluations - collection of polynomial evaluations.
      Throws:
      IllegalArgumentException - if provided number of evaluations is less than the required minimum.

    • PolynomialRobustEstimator

      protected PolynomialRobustEstimator(PolynomialRobustEstimatorListener listener)
      Constructor.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.

    • PolynomialRobustEstimator

      protected PolynomialRobustEstimator(int degree, List<PolynomialEvaluation> evaluations)
      Constructor.
      Parameters:
      degree - degree of polynomial to be estimated.
      evaluations - collection of polynomial evaluations.
      Throws:
      IllegalArgumentException - if provided degree is less than 1 or if provided number of evaluations is less than the required minimum for provided degree.

    • PolynomialRobustEstimator

      protected PolynomialRobustEstimator(int degree, PolynomialRobustEstimatorListener listener)
      Constructor.
      Parameters:
      degree - degree of polynomial to be estimated.
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Throws:
      IllegalArgumentException - if provided degree is less than 1.

    • PolynomialRobustEstimator

      protected PolynomialRobustEstimator(List<PolynomialEvaluation> evaluations, PolynomialRobustEstimatorListener listener)
      Constructor.
      Parameters:
      evaluations - collection of polynomial evaluations.
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Throws:
      IllegalArgumentException - if provided number of evaluations is less than the required minimum.

    • PolynomialRobustEstimator

      protected PolynomialRobustEstimator(int degree, List<PolynomialEvaluation> evaluations, PolynomialRobustEstimatorListener listener)
      Constructor.
      Parameters:
      degree - degree of polynomial to be estimated.
      evaluations - collection of polynomial evaluations.
      listener - listener to be notified of events.
      Throws:
      IllegalArgumentException - if provided degree is less than 1 or if provided number of evaluations is less than the required minimum for provided degree.

  • Method Details

    • getEvaluations

      public List<PolynomialEvaluation> getEvaluations()
      Gets collection of polynomial evaluations and their corresponding point of evaluation used to determine a polynomial of required degree.
      Returns:
      collection of polynomial evaluations.

    • setEvaluations

      public void setEvaluations(List<PolynomialEvaluation> evaluations) throws LockedException
      Sets collection of polynomial evaluations and their corresponding point of evaluation used to determine a polynomial of required degree.
      Parameters:
      evaluations - collection of polynomial evaluations.
      Throws:
      LockedException - if estimator is locked.
      IllegalArgumentException - if provided list of evaluations does not contain enough evaluations to estimate the polynomial using current settings.

    • getMinNumberOfEvaluations

      public int getMinNumberOfEvaluations()
      Gets minimum number of evaluations required to estimate a polynomial of the specified degree.
      Returns:
      number of required evaluations.

    • getListener

      public PolynomialRobustEstimatorListener getListener()
      Gets listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Returns:
      listener to be notified of events.

    • setListener

      public void setListener(PolynomialRobustEstimatorListener listener)
      Sets listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Parameters:
      listener - listener to be notified of events.

    • isLocked

      public boolean isLocked()
      Indicates if this estimator is locked because an estimation is being computed.
      Returns:
      true if this estimator is locked, false otherwise.

    • getProgressDelta

      public float getProgressDelta()
      Returns amount of progress variation before notifying a progress change during estimation.
      Returns:
      amount of progress variation before notifying a progress change during estimation.

    • setProgressDelta

      public void setProgressDelta(float progressDelta) throws LockedException
      Sets amount of progress variation before notifying a progress change during estimation.
      Parameters:
      progressDelta - amount of progress variation before notifying a progress change during estimation.
      Throws:
      IllegalArgumentException - if progress delta is less than zero or greater than 1.
      LockedException - if this estimator is locked because an estimation is being computed.

    • getConfidence

      public double getConfidence()
      Returns amount of confidence expressed as a value between 0.0 and 1.0 (which is equivalent to 100%). The amount of confidence indicates the probability that the estimated result is correct. Usually this value will be close to 1.0, but not exactly 1.0.
      Returns:
      amount of confidence as a value between 0.0 and 1.0.

    • setConfidence

      public void setConfidence(double confidence) throws LockedException
      Sets amount of confidence expressed as a value between 0.0 and 1.0 (which is equivalent to 100%). The amount of confidence indicates the probability that the estimated result is correct. Usually this value will be close to 1.0 but not exactly 1.0.
      Parameters:
      confidence - confidence to be set as a value between 0.0 and 1.0.
      Throws:
      IllegalArgumentException - if provided value is not between 0.0 and 1.0.
      LockedException - if this estimator is locked because an estimator is being computed.

    • getMaxIterations

      public int getMaxIterations()
      Returns maximum allowed number of iterations. If maximum allowed number of iterations is achieved without converging to a result when calling estimate(), a RobustEstimatorException will be raised.
      Returns:
      maximum allowed number of iterations.

    • setMaxIterations

      public void setMaxIterations(int maxIterations) throws LockedException
      Sets maximum allowed number of iterations. When the maximum number of iterations is exceeded, result will not be available, however an approximate result will be available for retrieval.
      Parameters:
      maxIterations - maximum allowed number of iterations to be set.
      Throws:
      IllegalArgumentException - if provided value is less than 1.
      LockedException - if this estimator is locked because an estimation is being computed.

    • isGeometricDistanceUsed

      public boolean isGeometricDistanceUsed()
      Indicates whether geometric distance will be used to find outliers or algebraic distance will be used instead.
      Returns:
      true if geometric distance is used, false otherwise.

    • setGeometricDistanceUsed

      public void setGeometricDistanceUsed(boolean geometricDistanceUsed) throws LockedException
      Specifies whether geometric distance will be used to find outliers or algebraic distance will be used instead.
      Parameters:
      geometricDistanceUsed - true if geometric distance is used, false otherwise.
      Throws:
      LockedException - if this estimator is locked.

    • getDegree

      public int getDegree()
      Gets degree of polynomial to be estimated.
      Returns:
      degree of polynomial to be estimated.

    • setDegree

      public void setDegree(int degree) throws LockedException
      Sets degree of polynomial to be estimated.
      Parameters:
      degree - degree of polynomial to be estimated.
      Throws:
      IllegalArgumentException - if provided degree is less than 1.
      LockedException - if this instance is locked.

    • isReady

      public boolean isReady()
      Determines whether estimation is ready to start with the given data and required degree of polynomial to be estimated.
      Returns:
      true if estimator is ready, false otherwise.

    • getQualityScores

      public double[] getQualityScores()
      Returns quality scores corresponding to each polynomial evaluation. The larger the score value the better the quality of the evaluation. This implementation always returns null. Subclasses using quality scores must implement proper behaviour.
      Returns:
      quality scores corresponding to each evaluation.

    • setQualityScores

      public void setQualityScores(double[] qualityScores) throws LockedException
      Sets quality scores corresponding to each polynomial evaluation. The larger the score value the better the quality of the evaluation. This implementation makes no action. Subclasses using quality scores must implement proper behaviour.
      Parameters:
      qualityScores - quality scores corresponding to each evaluation.
      Throws:
      LockedException - if robust estimator is locked because an estimation is already in progress.
      IllegalArgumentException - if provided quality scores length is smaller than minimum required number of evaluations.

    • estimate

      public abstract Polynomial estimate() throws LockedException, NotReadyException, RobustEstimatorException
      Estimates polynomial.
      Returns:
      estimated polynomial.
      Throws:
      LockedException - if robust estimator is locked because an estimation is already in progress.
      NotReadyException - if provided input data is not enough to start the estimation.
      RobustEstimatorException - if estimation fails for any other reason (i.e. numerical instability, no solution available, etc).

    • getMethod

      public abstract RobustEstimatorMethod getMethod()
      Returns method being used for robust estimation.
      Returns:
      method being used for robust estimation.

    • create

      public static PolynomialRobustEstimator create()
      Creates a robust polynomial estimator using default method.
      Returns:
      an instance of a robust polynomial estimator.

    • create

      public static PolynomialRobustEstimator create(int degree)
      Creates a robust polynomial estimator using provided degree and default method.
      Parameters:
      degree - degree of polynomial to be estimated.
      Returns:
      an instance of a robust polynomial estimator.
      Throws:
      IllegalArgumentException - if provided degree is less than 1.

    • create

      public static PolynomialRobustEstimator create(List<PolynomialEvaluation> evaluations)
      Creates a robust polynomial estimator using provided evaluations and default method.
      Parameters:
      evaluations - collection of polynomial evaluations.
      Returns:
      an instance of a robust polynomial estimator.

    • create

      public static PolynomialRobustEstimator create(PolynomialRobustEstimatorListener listener)
      Creates a robust polynomial estimator using provided listener and default method.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Returns:
      an instance of a robust polynomial estimator.

    • create

      public static PolynomialRobustEstimator create(int degree, List<PolynomialEvaluation> evaluations)
      Creates a robust polynomial estimator using provided degree, evaluations and default method.
      Parameters:
      degree - degree of polynomial to be estimated.
      evaluations - collection of polynomial evaluations.
      Returns:
      an instance of a robust polynomial estimator.
      Throws:
      IllegalArgumentException - if provided degree is less than 1.

    • create

      public static PolynomialRobustEstimator create(int degree, PolynomialRobustEstimatorListener listener)
      Creates a robust polynomial estimator using provided degree, listener and default method.
      Parameters:
      degree - degree of polynomial to be estimated.
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Returns:
      an instance of a robust polynomial estimator.
      Throws:
      IllegalArgumentException - if provided degree is less than 1.

    • create

      public static PolynomialRobustEstimator create(List<PolynomialEvaluation> evaluations, PolynomialRobustEstimatorListener listener)
      Creates a robust polynomial estimator using provided evaluations, listener and default method.
      Parameters:
      evaluations - collection of polynomial evaluations.
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Returns:
      an instance of a robust polynomial estimator.

    • create

      public static PolynomialRobustEstimator create(int degree, List<PolynomialEvaluation> evaluations, PolynomialRobustEstimatorListener listener)
      Creates a robust polynomial estimator using provided degree, evaluations, listener and default method.
      Parameters:
      degree - degree of polynomial to be estimated.
      evaluations - collection of polynomial evaluations.
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Returns:
      an instance of a robust polynomial estimator.
      Throws:
      IllegalArgumentException - if provided degree is less than 1.

    • create

      public static PolynomialRobustEstimator create(RobustEstimatorMethod method)
      Creates a robust polynomial estimator using provided method.
      Parameters:
      method - method of a robust polynomial estimator.
      Returns:
      an instance of a robust polynomial estimator.

    • create

      public static PolynomialRobustEstimator create(int degree, RobustEstimatorMethod method)
      Creates a robust polynomial estimator using provided degree and method.
      Parameters:
      degree - degree of polynomial to be estimated.
      method - method of a robust polynomial estimator.
      Returns:
      an instance of a robust polynomial estimator.
      Throws:
      IllegalArgumentException - if provided degree is less than 1.

    • create

      public static PolynomialRobustEstimator create(List<PolynomialEvaluation> evaluations, RobustEstimatorMethod method)
      Creates a robust polynomial estimator using provided evaluations and method.
      Parameters:
      evaluations - collection of polynomial evaluations.
      method - method of a robust polynomial estimator.
      Returns:
      an instance of a robust polynomial estimator.

    • create

      public static PolynomialRobustEstimator create(PolynomialRobustEstimatorListener listener, RobustEstimatorMethod method)
      Creates a robust polynomial estimator using provided listener and method.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      method - method of a robust polynomial estimator.
      Returns:
      an instance of a robust polynomial estimator.

    • create

      public static PolynomialRobustEstimator create(int degree, List<PolynomialEvaluation> evaluations, RobustEstimatorMethod method)
      Creates a robust polynomial estimator using provided degree, evaluations and method.
      Parameters:
      degree - degree of polynomial to be estimated.
      evaluations - collection of polynomial evaluations.
      method - method of a robust polynomial estimator.
      Returns:
      an instance of a robust polynomial estimator.
      Throws:
      IllegalArgumentException - if provided degree is less than 1.

    • create

      public static PolynomialRobustEstimator create(int degree, PolynomialRobustEstimatorListener listener, RobustEstimatorMethod method)
      Creates a robust polynomial estimator using provided degree, listener and method.
      Parameters:
      degree - degree of polynomial to be estimated.
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      method - method of a robust polynomial estimator.
      Returns:
      an instance of a robust polynomial estimator.
      Throws:
      IllegalArgumentException - if provided degree is less than 1.

    • create

      public static PolynomialRobustEstimator create(List<PolynomialEvaluation> evaluations, PolynomialRobustEstimatorListener listener, RobustEstimatorMethod method)
      Creates a robust polynomial estimator using provided evaluations, listener and method.
      Parameters:
      evaluations - collection of polynomial evaluations.
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      method - method of a robust polynomial estimator.
      Returns:
      an instance of a robust polynomial estimator.

    • create

      public static PolynomialRobustEstimator create(int degree, List<PolynomialEvaluation> evaluations, PolynomialRobustEstimatorListener listener, RobustEstimatorMethod method)
      Creates a robust polynomial estimator using provided degree, evaluations, listener and method.
      Parameters:
      degree - degree of polynomial to be estimated.
      evaluations - collection of polynomial evaluations.
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      method - method of a robust polynomial estimator.
      Returns:
      an instance of a robust polynomial estimator.
      Throws:
      IllegalArgumentException - if provided degree is less than 1.

    • getDistance

      protected double getDistance(PolynomialEvaluation eval, Polynomial polynomial)
      Computes geometric or algebraic distance between provided polynomial and evaluation.
      Parameters:
      eval - polynomial evaluation.
      polynomial - polynomial.
      Returns:
      distance.

    • getAlgebraicDistance

      protected double getAlgebraicDistance(PolynomialEvaluation eval, Polynomial polynomial)
      Computes algebraic distance between provided polynomial and evaluation.
      Parameters:
      eval - polynomial evaluation.
      polynomial - polynomial.
      Returns:
      algebraic distance.

    • getAlgebraicDistance

      protected double getAlgebraicDistance(DirectPolynomialEvaluation eval, Polynomial polynomial)
      Computes algebraic distance of between provided polynomial and direct evaluation.
      Parameters:
      eval - direct polynomial evaluation.
      polynomial - polynomial.
      Returns:
      algebraic distance.

    • getAlgebraicDistance

      protected double getAlgebraicDistance(DerivativePolynomialEvaluation eval, Polynomial polynomial)
      Computes algebraic distance of a derivative between provided polynomial and evaluation.
      Parameters:
      eval - derivative polynomial evaluation.
      polynomial - polynomial.
      Returns:
      algebraic distance.

    • getAlgebraicDistance

      protected double getAlgebraicDistance(IntegralPolynomialEvaluation eval, Polynomial polynomial)
      Computes algebraic distance of an integral between provided polynomial and evaluation.
      Parameters:
      eval - integration polynomial evaluation.
      polynomial - polynomial.
      Returns:
      algebraic distance.

    • getAlgebraicDistance

      protected double getAlgebraicDistance(IntegralIntervalPolynomialEvaluation eval, Polynomial polynomial)
      Computes algebraic distance of an integration interval between provided polynomial and evaluation.
      Parameters:
      eval - integration interval polynomial evaluation.
      polynomial - polynomial.
      Returns:
      algebraic distance.

    • getGeometricOrAlgebraicDistance

      protected double getGeometricOrAlgebraicDistance(PolynomialEvaluation eval, Polynomial polynomial)
      Commutes distance of evaluation respect to provided polynomial in a geometric sense if evaluation is direct, otherwise returns algebraic distance.
      Parameters:
      eval - polynomial evaluation.
      polynomial - polynomial.
      Returns:
      geometric distance for direct evaluation or algebraic distance otherwise.

    • getGeometricDistance

      protected double getGeometricDistance(DirectPolynomialEvaluation eval, Polynomial polynomial)
      Computes distance of evaluation respect to provided polynomial in a geometric sense by computing a tangent line to polynomial at point x and comparing the distance of such line to provided evaluation point.
      Parameters:
      eval - polynomial evaluation.
      polynomial - polynomial.
      Returns:
      geometric distance.

    • internalSetEvaluations

      private void internalSetEvaluations(List<PolynomialEvaluation> evaluations)
      Sets list of polynomial evaluations. This method does not check whether estimator is locked.
      Parameters:
      evaluations - list of polynomial evaluations to estimate polynomial.
      Throws:
      IllegalArgumentException - if provided list of polynomials is null or too small.