contrib/rpl/rrel/rrel_muset_obj.h
Go to the documentation of this file.
00001 #ifndef rrel_muset_obj_h_
00002 #define rrel_muset_obj_h_
00003 //:
00004 //  \file
00005 //  \author Chuck Stewart
00006 //  \date   Summer 2001
00007 //  The MUSET (MUSE trimmed) objective function., which should be used instead of LMS.
00008
00009 #include <rrel/rrel_objective.h>
00010
00011 class rrel_muse_table;
00012
00013 enum rrel_muse_type { RREL_MUSE_TRIMMED, RREL_MUSE_TRIMMED_SQUARE, RREL_MUSE_QUANTILE };
00014
00015 //: The MUSET (MUSE trimmed) objective function, which should be used instead of LMS.
00016 //  MUSE is a robust objective function in the spirit of LMS/LTS
00017 //  (least-median-of-squares / least-trimmed-squares).  In fact, it
00018 //  can be considered a generalization of these objective functions.
00019 //  It can be used in place of them and it really SHOULD because it
00020 //  (a) produces much better results, regardless of the inlier
00021 //  fraction, and (b) (unlike RANSAC) can tolerate large fractions of
00022 //  outliers WITHOUT prior knowledge of scale.  It should be used in
00023 //  combination with a random sampling search and an appropriate problem
00024 //  representation.
00025 //
00026 //  Rather than assuming a fixed minimum fraction of inliers and then
00027 //  building an objective function based on either the order
00028 //  statistics (e.g. the median) or the trimmed statistics, MUSE
00029 //  ADAPTIVELY determines the inlier fraction and computes its
00030 //  objective function from this inlier fraction.   It does this by
00031 //  converting the fitting error (residual) order statistics into
00032 //  scale estimates, normalizing these, and then choosing the
00033 //  smallest.  The version given here is called MUSET, because it is
00034 //  based on trimmed statistics.  This is described in Chapter 4 of
00035 //  Jim Miller's thesis.  A new paper describing MUSE will be written
00036 //  in the autumn of 2001.
00037 //
00038 //  MUSE requires a look-up table to compute its normalizing
00039 //  parameters.  If it does not get one, the constructor builds it.
00040 //  MUSE also requires the minimum and maximum possible inlier
00041 //  fractions in the data.  Usually it is safe to leave the maximum
00042 //  fraction at 0.95.  The minimum inlier fraction determines the
00043 //  random sampling parameters, so it should be set with some care.
00044 //  Setting it too low can cause a lot of unnecessary search.
00045 //  Setting it too high can cause small structures to be missed.
00046 //
00047 //  Finally, MUSE internally contains an additional step called sk
00048 //  refinement, which increases its ability to distinguish small
00049 //  scale structures.  In general it is safe to use this, and the
00050 //  constructor defaults to having it set.
00051
00052 class rrel_muset_obj : public rrel_objective
00053 {
00054  public:
00055   //: Constructor.
00056   //  \a max_n is the size of the look-up table.
00057   rrel_muset_obj( int max_n, bool use_sk_refine=true);
00058
00059   //: Constructor with previously computed table.
00060   //  \a table will be used as the look-up table.
00061   rrel_muset_obj( rrel_muse_table* table, bool use_sk_refine=true);
00062
00063   //: Destructor.
00064   ~rrel_muset_obj();
00065
00066   //: Evaluate the objective function on heteroscedastic residuals.
00067   //  \sa rrel_objective::fcn.
00068   virtual double fcn( vect_const_iter res_begin, vect_const_iter res_end,
00069                       vect_const_iter /* scale is unused */,
00070                       vnl_vector<double>* = 0 /* param vector is unused */ ) const;
00071
00072   //: Evaluate the objective function on homoscedastic residuals.
00073   //  \sa rrel_objective::fcn.
00074   virtual double fcn( vect_const_iter begin, vect_const_iter end,
00075                       double = 0 /* scale is unused */,
00076                       vnl_vector<double>* = 0 /* param vector is unused */ ) const;
00077
00078   //: Computes the MUSE estimate and best value of k
00079   //  \a begin and \a end give the residuals. \a objective is the
00080   //  value of the objective function, \a sigma_est is an estimate
00081   //  of the scale (and is the objective function), and \a best_k
00082   //  is the value of k that produced the scale estimate.
00083   void internal_fcn( vect_const_iter begin, vect_const_iter end,
00084                      double& sigma_est, int& best_k ) const;
00085
00086   //: False.
00087   //  This MUSE estimator is based on trimmed statistics, and does not
00088   //  use a scale estimate.
00089   virtual bool requires_prior_scale() const
00090     { return false; }
00091
00092   //: True, since MUSE can estimate scale.
00093   //  \sa rrel_objective::can_estimate_scale.
00094   virtual bool can_estimate_scale() const { return true; }
00095
00096   //: Scale estimate.
00097   virtual double scale( vect_const_iter res_begin, vect_const_iter res_end ) const;
00098
00099   //: Set the minimum fraction of the data that are inliers.
00100   void set_min_inlier_fraction( double min_frac=0.25 )
00101     {  min_frac_ = min_frac; }
00102
00103   //: Set the maximum fraction of the data that could be inliers.
00104   void set_max_inlier_fraction( double max_frac=0.95 )
00105     {  max_frac_ = max_frac; }
00106
00107   //: The increment to use in testing different inlier/outlier fractions.
00108   void set_inlier_fraction_increment( double frac_inc=0.05 )
00109     {  frac_inc_ = frac_inc; }
00110
00111   //: The minimum fraction of the data that must be inliers.
00112   double min_inlier_fraction() const { return min_frac_; }
00113
00114   //: The maximum fraction of the data that could be inliers.
00115   double max_inlier_fraction() const { return max_frac_; }
00116
00117   //: The search step for determining the inlier/outlier fraction.
00118   double inlier_fraction_increment() const { return frac_inc_; }
00119
00120   //: Set the type of MUSE objective function
00121   void set_muse_type( rrel_muse_type t = RREL_MUSE_TRIMMED )
00122     { muse_type_ = t; }
00123
00124   //: Access the type of MUSE objective function
00125   rrel_muse_type muse_type() const { return muse_type_; }
00126
00127  protected:
00128   bool use_sk_refine_;
00129   rrel_muse_type muse_type_;
00130
00131   bool table_owned_;
00132   rrel_muse_table* table_;
00133   double min_frac_;
00134   double max_frac_;
00135   double frac_inc_;
00136 };
00137
00138 #endif