source: branches/0.4-stable/yat/classifier/SupervisedClassifier.h @ 1392

#ifndef _theplu_yat_classifier_supervisedclassifier_ 
#define _theplu_yat_classifier_supervisedclassifier_ 

// $Id$

/*
  Copyright (C) 2005 Markus Ringnér
  Copyright (C) 2006 Jari Häkkinen, Peter Johansson, Markus Ringnér
  Copyright (C) 2007 Jari Häkkinen, Peter Johansson
  Copyright (C) 2008 Peter Johansson, Markus Ringnér

  This file is part of the yat library, http://dev.thep.lu.se/yat

  The yat library is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of the
  License, or (at your option) any later version.

  The yat library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  02111-1307, USA.
*/

#include <cstddef>

namespace theplu {
namespace yat {

  namespace utility {
    class Matrix;
  }

namespace classifier {  

  class MatrixLookup;
  class MatrixLookupWeighted;
  class Target;

  /**
     \brief Interface class for supervised classifiers that use data
     in a matrix format.

     The data matrix is organized with data points (samples) as
     columns with rows corresponding to variables for the data
     points. Supervised classifiers that do not use data in this
     format include kernel-based classifiers such as SVM. A supervised
     %classifier is trained on training data for which a class of each
     data point is known and used in the training. A trained
     supervised %classifier can be used to predict the class of test
     samples.
  */
  class SupervisedClassifier
  {
   
  public:
    /**
       \brief Constructor
    */
    SupervisedClassifier(void);
    

    /**
       \brief Destructor
    */
    virtual ~SupervisedClassifier(void);


    /**
       @brief Create an untrained copy of the %classifier.
       
       An interface for making new %classifier objects. This function
       allows for specification at run-time of which %classifier type
       to instatiate (see 'Prototype' in Design Patterns). Derived
       classes should implement this function with DerivedClass* as
       the return type and not SupervisedClassifier*. A dynamically
       allocated DerivedClassifier should be returned. The implementation
       of this function should correspond to a copy constructor with
       the exception that the returned %classifier is not trained.
       
       @returns A dynamically allocated %classifier, which has
       to be deleted by the caller to avoid memory leaks.
    */
    virtual SupervisedClassifier* 
    make_classifier() const =0;
    

    /**
       \brief Make predictions for unweighted test data.
       
       Samples in \a data are predicted and predictions for all
       classes are returned in \a result.  The test data \a data
       should have one column per test sample and one row for each
       variable measured for the test samples. The rows of \a data
       should be ordered identical to the rows of the data used to
       train the %classifier, so that a given row corresponds to the
       same variable for both training and test data. The predictions
       in \a result have one column for each sample in \a data,
       ordered in the same order, and one row for each class as
       defined by the targets used to train the %classifier. Derived
       classes should implement this function such that unweighted
       calculations are used throughout when both training and test
       data are unweighted.
    */        
    virtual void predict(const MatrixLookup& data, utility::Matrix& result) const =0;   


    /**
       \brief Make predictions for weighted test data.
       
       Both \a data and \a result follow the description for
       predict(const MatrixLookup& data, utility::Matrix& result).
    */
    virtual void predict(const MatrixLookupWeighted& data, utility::Matrix& result) const =0;   


    /**
       \brief Train the %classifier using unweighted training data with known
       targets. 
    
       The training data \a data should have one column per training
       sample and one row for each variable measured for the training
       samples. The size of \a target should be the number of samples
       in \a data and \a target should contain the class for each
       sample ordered in the same order as columns in \a data.
    */
    virtual void train(const MatrixLookup& data, const Target& targets)=0;
    
    /**
       \brief Train the %classifier using weighted training data with
       known targets. 
       
       Both \a data and \a targets should follow the description for
       train(const MatrixLookup& data, const Target& targets).
    */
    virtual void train(const MatrixLookupWeighted& data, const Target& targets)=0;

  };  
  
}}} // of namespace classifier, yat, and theplu

#endif