Package com.irurueta.numerical.robust

Class LMedSRobustEstimator<T>

java.lang.Object
com.irurueta.numerical.robust.RobustEstimator<T>
com.irurueta.numerical.robust.LMedSRobustEstimator<T>
Type Parameters:
T - type of object to be estimated.
public class LMedSRobustEstimator<T> extends RobustEstimator<T>
This class implements LMedS (Least Median of Squares) algorithm to robustly estimate a data model. LMedS is based on the idea that a given proportion of outliers exists in the total amount of samples provided. This algorithm tries to iteratively find the beast subset of samples picking the ones with the least median of error. To determine whether a sample is an outlier or not, and the estimated error for each sample, provided listener must be used. Contrary to RANSAC, this algorithm does not require a fixed threshold to be set to determine whether samples are inliers or not. Instead, threshold is computed dynamically. Because of that LMedS typically produces results with larger error than RANSAC having a similar computational cost, because samples usually contain a large error. Hence, if threshold is known in advance for a given estimation, RANSAC should be preferred rather than LMedS. On the contrary, if it can be ensured that samples are very accurate except for some outliers, then LMedS becomes much more accurate than RANSAC because it typically converges to a solution with a very small threshold. However, typically inlier samples tend to have certain error, and in practice LMedS produces results with a similar accuracy and computational cost than RANSAC.

  • Field Details

    • 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_STOP_THRESHOLD

      public static final double DEFAULT_STOP_THRESHOLD
      Default value to be used for stop threshold. Stop threshold can be used to keep the algorithm iterating in case that best threshold is not small enough. Once a better solution is found yielding a threshold smaller than this value, the algorithm will stop.
      See Also:

    • MIN_STOP_THRESHOLD

      public static final double MIN_STOP_THRESHOLD
      Minimum allowed stop threshold value.
      See Also:

    • DEFAULT_INLIER_FACTOR

      public static final double DEFAULT_INLIER_FACTOR
      Default factor to normalize threshold to determine inliers. This factor can be used to increase or lower the dynamically computed threshold so that the algorithm becomes more or less accurate. The stricter the threshold (lower factor), the more time the algorithm will need to converge, if it can converge. By default, the factor is 1.0, which makes the threshold to be computed as the median of residuals.
      See Also:

    • MIN_INLER_FACTOR

      public static final double MIN_INLER_FACTOR
      Minimum allowed value for inlier factor.
      See Also:

    • STD_CONSTANT

      public static final double STD_CONSTANT
      Constant to estimate standard deviation of residuals based on their median.
      See Also:

    • confidence

      private double confidence
      Amount of confidence expressed as a value between 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

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

    • subsetSelector

      private SubsetSelector subsetSelector
      Instance in charge of picking random subsets of samples.

    • iters

      private int iters
      Number of iterations to be done to obtain required confidence.

    • bestResult

      private T bestResult
      Best solution that has been found so far during an estimation.

    • bestInliersData

      private LMedSRobustEstimator.LMedSInliersData bestInliersData
      Data related to inliers found for best result.

    • stopThreshold

      private double stopThreshold
      Threshold to be used to keep the algorithm iterating in case that best threshold is not small enough. Once a better solution is found yielding a threshold smaller than this value, the algorithm will stop.

    • inlierFactor

      private double inlierFactor
      Factor to normalize threshold to determine inliers. This factor can be used to increase or lower the dynamically computed threshold so that the algorithm becomes more or less accurate. The stricter the threshold (lower factor), the more time the algorithm will need to converge, if it can converge. By default, the factor is 1.0, which makes the threshold to be computed as the median of residuals.

  • Constructor Details

    • LMedSRobustEstimator

      public LMedSRobustEstimator()
      Constructor.

    • LMedSRobustEstimator

      public LMedSRobustEstimator(LMedSRobustEstimatorListener<T> listener)
      Constructor with listener.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes, as well as in charge of picking samples and doing per-iteration estimations.

  • Method Details

    • getConfidence

      public double getConfidence()
      Returns amount of confidence expressed as a value between 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 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 estimation is being computed.

    • getMaxIterations

      public int getMaxIterations()
      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.
      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.

    • getStopThreshold

      public double getStopThreshold()
      Returns threshold to be used to keep the algorithm iterating in case that best threshold is not small enough. Once a better solution is found yielding a threshold smaller than this value, the algorithm will stop.
      Returns:
      threshold to be used to keep the algorithm iterating in case that best threshold is not small enough.

    • setStopThreshold

      public void setStopThreshold(double stopThreshold) throws LockedException
      Sets threshold to be used to keep the algorithm iterating in case that best threshold is not small enough. Once a better solution is found yielding a threshold smaller than this vlaue, the algorithm will stop.
      Parameters:
      stopThreshold - threshold to be used to keep the algorithm iterating in case that best threshold is not small enough.
      Throws:
      IllegalArgumentException - if provided value is less or equal than 0.0.
      LockedException - if this estimator is locked because an estimation is being computed.

    • getInlierFactor

      public double getInlierFactor()
      Returns factor to normalize or adjust threshold to determine inliers. This factor can be used to increase or lower the dynamically computed threshold so that the algorithm becomes more or less accurate. The stricter the threshold (lower factor), the more time the algorithm will need to converge, if it can converge. By default, the factor is 1.0, which makes the threshold to be computed as the median of residuals.
      Returns:
      factor to normalize threshold to determine inliers.

    • setInlierFactor

      public void setInlierFactor(double inlierFactor) throws LockedException
      Sets factor to normalize or adjust threshold to determine inliers. This factor can be used to increase or lower the dynamically computed threshold so that the algorithm becomes more or less accurate. The stricter the threshold (lower factor), the more time the algorithm will need to converge, if it can converge. By default, the factor is 1.0, which makes the threshold to be computed as the median of residuals.
      Parameters:
      inlierFactor - inlier factor to be set.
      Throws:
      IllegalArgumentException - if provided value is less or equal than 0.0.
      LockedException - if this estimator is locked because an estimation is being computed.

    • getNIters

      public int getNIters()
      Returns number of iterations to be done to obtain required confidence.
      Returns:
      number of iterations to be done to obtain required confidence.

    • getBestResult

      public T getBestResult()
      Returns best solution that has been found so far during an estimation.
      Returns:
      best solution that has been found so far during an estimation.

    • getBestInliersData

      public LMedSRobustEstimator.LMedSInliersData getBestInliersData()
      Returns data related to inliers found for best result.
      Returns:
      data related to inliers found for best result.

    • isReady

      public boolean isReady()
      Indicates if estimator is ready to start the estimation process.
      Overrides:
      isReady in class RobustEstimator<T>
      Returns:
      true if ready, false otherwise.

    • estimate

      public T estimate() throws LockedException, NotReadyException, RobustEstimatorException
      Robustly estimates an instance of T.
      Specified by:
      estimate in class RobustEstimator<T>
      Returns:
      estimated object.
      Throws:
      LockedException - if robust estimator is locked.
      NotReadyException - if provided input data is not enough to start the estimation.
      RobustEstimatorException - if estimation fails for any reason (i.e. numerical instability, no solution available, etc).

    • getInliersData

      public InliersData getInliersData()
      Returns data about inliers once estimation has been done.
      Specified by:
      getInliersData in class RobustEstimator<T>
      Returns:
      data about inliers or null if estimation has not been done.

    • getMethod

      public RobustEstimatorMethod getMethod()
      Returns method being used for robust estimation.
      Specified by:
      getMethod in class RobustEstimator<T>
      Returns:
      method being used for robust estimation.

    • computeInliers

      private static <T> void computeInliers(T iterResult, int subsetSize, double inlierFactor, double[] residualsTemp, LMedSRobustEstimatorListener<T> listener, com.irurueta.sorting.Sorter<Double> sorter, LMedSRobustEstimator.LMedSInliersData inliersData)
      Computes inliers data for current iteration.
      Type Parameters:
      T - type of result to be estimated.
      Parameters:
      iterResult - result to be tested on current iteration.
      subsetSize - subset sample size to be picked on each iteration.
      inlierFactor - factor to adjust threshold to determine whether samples are inliers or not.
      residualsTemp - temporal array to store residuals, since median computation requires modifying the original array.
      listener - listener to obtain residuals for samples.
      sorter - sorter instance to compute median of residuals.
      inliersData - inliers data to be reused on each iteration.