Changeset 1188 for trunk/yat/classifier


Ignore:
Timestamp:
Feb 29, 2008, 11:14:04 AM (13 years ago)
Author:
Markus Ringnér
Message:

Fixed KNN and SupervisedClassfier? for #75

Location:
trunk/yat/classifier
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/yat/classifier/KNN.h

    r1164 r1188  
    4343namespace classifier {
    4444
    45   ///
    46   /// @brief Class for Nearest Neigbor Classification.
    47   ///
    48   /// The template argument Distance should be a class modelling
    49   /// the concept \ref concept_distance.
    50   /// The template argument NeigborWeighting should be a class modelling
    51   /// the concept \ref concept_neighbor_weighting.
    52 
     45  /**
     46     @brief Nearest Neighbor Classifier
     47     
     48     A sample is predicted based on the classes of its k nearest
     49     neighbors among the training data samples. KNN supports using
     50     different measures, for example, Euclidean distance, to define
     51     distance between samples. KNN also supports using different ways to
     52     weight the votes of the k nearest neighbors. For example, using a
     53     uniform vote a test sample gets a vote for each class which is the
     54     number of nearest neighbors belonging to the class.
     55     
     56     The template argument Distance should be a class modelling the
     57     concept \ref concept_distance. The template argument
     58     NeighborWeighting should be a class modelling the concept \ref
     59     concept_neighbor_weighting.
     60  */
    5361  template <typename Distance, typename NeighborWeighting=KNN_Uniform>
    5462  class KNN : public SupervisedClassifier
     
    5664   
    5765  public:
    58     ///
    59     /// @brief Constructor
    60     ///
     66    /**
     67       @brief Default constructor.
     68       
     69       The number of nearest neighbors (k) is set to 3. Distance and
     70       NeighborWeighting are initialized using their default
     71       constructuors.
     72    */
    6173    KNN(void);
    6274
    6375
    64     ///
    65     /// @brief Constructor
    66     ///
     76    /**
     77       @brief Constructor using an intialized distance measure.
     78       
     79       The number of nearest neighbors (k) is set to 3. This constructor
     80       should be used if Distance has parameters and the user wants
     81       to specify the parameters by initializing Distance prior to
     82       constructing the KNN.
     83    */
    6784    KNN(const Distance&);
    6885
    6986
    70     ///
    71     /// @brief Destructor
    72     ///
     87    /**
     88      Destructor
     89    */
    7390    virtual ~KNN();
    7491   
    75 
    76     ///
    77     /// Default number of neighbors (k) is set to 3.
    78     ///
    79     /// @return the number of neighbors
    80     ///
     92   
     93    /**
     94       \brief Get the number of nearest neighbors.
     95       \return The number of neighbors.
     96    */
    8197    u_int k() const;
    8298
    83     ///
    84     /// @brief sets the number of neighbors, k.
    85     ///
     99    /**
     100       \brief Set the number of nearest neighbors.
     101       
     102       Sets the number of neighbors to \a k_in.
     103    */
    86104    void k(u_int k_in);
    87105
     
    89107    KNN<Distance,NeighborWeighting>* make_classifier(void) const;
    90108   
    91     ///
    92     /// Train the classifier using training data and target.
    93     ///
    94     /// If the number of training samples set is smaller than \a k_in,
    95     /// k is set to the number of training samples.
    96     ///
    97     void train(const MatrixLookup&, const Target&);
    98 
    99     ///
    100     /// Train the classifier using weighted training data and target.
    101     ///
    102     void train(const MatrixLookupWeighted&, const Target&);
    103 
    104    
    105     ///
    106     /// For each sample, calculate the number of neighbors for each
    107     /// class.
    108     ///
    109     void predict(const MatrixLookup&, utility::Matrix&) const;
    110 
    111     ///
    112     /// For each sample, calculate the number of neighbors for each
    113     /// class.
    114     ///
    115     void predict(const MatrixLookupWeighted&, utility::Matrix&) const;
    116 
    117 
     109    /**
     110       @brief Make predictions for unweighted test data.
     111       
     112       Predictions are calculated and returned in \a results.  For
     113       each sample in \a data, \a results contains the weighted number
     114       of nearest neighbors which belong to each class. Numbers of
     115       nearest neighbors are weighted according to
     116       NeighborWeighting. If a class has no training samples NaN's are
     117       returned for this class in \a results.
     118    */
     119    void predict(const MatrixLookup& data , utility::Matrix& results) const;
     120
     121    /**   
     122        @brief Make predictions for weighted test data.
     123       
     124        Predictions are calculated and returned in \a results. For
     125        each sample in \a data, \a results contains the weighted
     126        number of nearest neighbors which belong to each class as in
     127        predict(const MatrixLookup& data, utility::Matrix& results).
     128        If a test and training sample pair has no variables with
     129        non-zero weights in common, there are no variables which can
     130        be used to calculate the distance between the two samples. In
     131        this case the distance between the two is set to infinity.
     132    */
     133    void predict(const MatrixLookupWeighted& data, utility::Matrix& results) const;
     134
     135
     136    /**
     137       @brief Train the KNN using unweighted training data with known
     138       targets.
     139       
     140       For KNN there is no actual training; the entire training data
     141       set is stored with targets. KNN only stores references to \a data
     142       and \a targets as copying these would make the %classifier
     143       slow. If the number of training samples set is smaller than k,
     144       k is set to the number of training samples.
     145       
     146       \note If \a data or \a targets go out of scope ore are
     147       deleted, the KNN becomes invalid and further use is undefined
     148       unless it is trained again.
     149    */
     150    void train(const MatrixLookup& data, const Target& targets);
     151   
     152    /**   
     153       \brief Train the KNN using weighted training data with known targets.
     154   
     155       See train(const MatrixLookup& data, const Target& targets) for
     156       additional information.
     157    */
     158    void train(const MatrixLookupWeighted& data, const Target& targets);
     159   
    118160  private:
    119 
     161   
    120162    const MatrixLookup* data_ml_;
    121163    const MatrixLookupWeighted* data_mlw_;
  • trunk/yat/classifier/SupervisedClassifier.h

    r1176 r1188  
    4242  class Target;
    4343
    44   ///
    45   /// @brief Interface class for supervised classifiers that use data
    46   /// in a matrix format with data points as columns and each row
    47   /// corresponding to a variable for the data points. Supervised
    48   /// classifiers that do not use data in this format include
    49   /// kernel-based classifiers such as SVM.
    50   ///
     44  /**
     45     \brief Interface class for supervised classifiers that use data
     46     in a matrix format.
     47
     48     The data matrix is organized with data points (samples) as
     49     columns with rows corresponding to variables for the data
     50     points. Supervised classifiers that do not use data in this
     51     format include kernel-based classifiers such as SVM. A supervised
     52     %classifier is trained on training data for which a class of each
     53     data point is known and used in the training. A trained
     54     supervised %classifier can be used to predict the class of test
     55     samples.
     56  */
    5157  class SupervisedClassifier
    5258  {
    5359   
    5460  public:
    55     ///
    56     /// @brief Constructor
    57     ///
     61    /**
     62       \brief Constructor
     63    */
    5864    SupervisedClassifier(void);
    5965   
    6066
    61     ///
    62     /// @brief Destructor
    63     ///
     67    /**
     68       \brief Destructor
     69    */
    6470    virtual ~SupervisedClassifier(void);
    6571
    6672
    67     ///
    68     /// An interface for making new %classifier objects. This function
    69     /// allows for specification at run-time of which %classifier type
    70     /// to instatiate (see 'Prototype' in Design Patterns). Derived
    71     /// classes should implement this function with DerivedClass* as
    72     /// the return type and not SupervisedClassifier*, and a
    73     /// dynamically allocated %classifier should be returned. The
    74     /// implementation of this function should correspond to a copy
    75     /// constructor with the exception that the returned %classifier
    76     /// is not trained.
    77     ///
    78     /// @note Returns a dynamically allocated %classifier, which has
    79     /// to be deleted by the caller to avoid memory leaks.
    80     ///
     73    /**
     74       @brief Create an untrained copy of the %classifier.
     75       
     76       An interface for making new %classifier objects. This function
     77       allows for specification at run-time of which %classifier type
     78       to instatiate (see 'Prototype' in Design Patterns). Derived
     79       classes should implement this function with DerivedClass* as
     80       the return type and not SupervisedClassifier*. A dynamically
     81       allocated DerivedClassifier should be returned. The implementation
     82       of this function should correspond to a copy constructor with
     83       the exception that the returned %classifier is not trained.
     84       
     85       @returns A dynamically allocated %classifier, which has
     86       to be deleted by the caller to avoid memory leaks.
     87    */
    8188    virtual SupervisedClassifier*
    8289    make_classifier() const =0;
    8390   
    8491
    85 
    86     ///
    87     /// Generate output values for a data set
    88     ///
    89     virtual void predict(const MatrixLookup&, utility::Matrix&) const =0;   
    90 
    91     ///
    92     /// Generate output values for a weighted data set
    93     ///
    94     virtual void predict(const MatrixLookupWeighted&, utility::Matrix&) const =0;   
     92    /**
     93       \brief Make predictions for unweighted test data.
     94       
     95       Samples in \a data are predicted and predictions for all
     96       classes are returned in \a result.  The test data \a data
     97       should have one column per test sample and one row for each
     98       variable measured for the test samples. The rows of \a data
     99       should be ordered identical to the rows of the data used to
     100       train the %classifier, so that a given row corresponds to the
     101       same variable for both training and test data. The predictions
     102       in \a result have one column for each sample in \a data,
     103       ordered in the same order, and one row for each class as
     104       defined by the targets used to train the %classifier. Derived
     105       classes should implement this function such that unweighted
     106       calculations are used throughout when both training and test
     107       data are unweighted.
     108    */       
     109    virtual void predict(const MatrixLookup& data, utility::Matrix& result) const =0;   
    95110
    96111
    97     ///
    98     /// Train the %classifier using unweighted training data and
    99     /// targets. The training data \a data should have one column per
    100     /// training sample and one row for each variable measured for the
    101     /// training samples. The size of \a target should be the number
    102     /// of samples in \a data and \a target should contain the class
    103     /// for each sample ordered in the same order as columns in \a data.
    104     ///
     112    /**
     113       \brief Make predictions for weighted test data.
     114       
     115       Both \a data and \a result follow the description for
     116       predict(const MatrixLookup& data, utility::Matrix& result).
     117    */
     118    virtual void predict(const MatrixLookupWeighted& data, utility::Matrix& result) const =0;   
     119
     120
     121    /**
     122       \brief Train the %classifier using unweighted training data with known
     123       targets.
     124   
     125       The training data \a data should have one column per training
     126       sample and one row for each variable measured for the training
     127       samples. The size of \a target should be the number of samples
     128       in \a data and \a target should contain the class for each
     129       sample ordered in the same order as columns in \a data.
     130    */
    105131    virtual void train(const MatrixLookup& data, const Target& targets)=0;
    106 
    107     ///
    108     /// Train the %classifier using weighted training data and
    109     /// targets. Both \a data and \a targets should follow the
    110     /// description for train(const MatrixLookup& data, const Target& targets)
    111     ///
     132   
     133    /**
     134       \brief Train the %classifier using weighted training data with
     135       known targets.
     136       
     137       Both \a data and \a targets should follow the description for
     138       train(const MatrixLookup& data, const Target& targets).
     139    */
    112140    virtual void train(const MatrixLookupWeighted& data, const Target& targets)=0;
    113141
Note: See TracChangeset for help on using the changeset viewer.