source: trunk/c++_tools/classifier/Kernel.h @ 648

#ifndef _theplu_classifier_kernel_
#define _theplu_classifier_kernel_

// $Id$

#include <c++_tools/classifier/DataLookup2D.h>
#include <c++_tools/classifier/KernelFunction.h>
#include <c++_tools/classifier/MatrixLookupWeighted.h>

#include <cctype>
#include <vector>

namespace theplu {
namespace classifier {

  class MatrixLookup;

  ///
  ///  @brief Abstract Base Class for Kernels. 
  ///
  ///  Class taking care of the \f$ NxN \f$ kernel matrix, where \f$ N \f$
  ///  is number of samples. Each element in the Kernel corresponds is
  ///  the scalar product of the corresponding pair of samples. At the
  ///  time being there are two kinds of kernels. Kernel_SEV that is
  ///  optimized to be fast and Kernel_MEV that is preferable when
  ///  dealing with many samples and memory might be a
  ///  bottleneck. Also there are the corresponding weighted versions
  ///  to deal with weights (including missing values). A
  ///  KernelFunction defines what kind of scalar product the Kernel
  ///  represents, e.g. a Polynomial Kernel of degree 1 means we are
  ///  dealing with the ordinary linear scalar product.
  ///
  /// @note If the KernelFunction is destroyed, the Kernel is no
  /// longer defined.
  ///
  class Kernel
  {
    
  public:

    ///
    /// Constructor taking the @a data matrix and KernelFunction as
    /// input. Each column in the data matrix corresponds to one
    /// sample and the Kernel matrix is built applying the
    /// KernelFunction on each pair of columns in the data matrix.
    ///
    /// @note Can not handle NaNs. 
    ///
    Kernel(const MatrixLookup& data, const KernelFunction& kf); 

    ///
    /// Constructor taking the @a data matrix (with weights) and
    /// KernelFunction as
    /// input. Each column in the data matrix corresponds to one
    /// sample and the Kernel matrix is built applying the
    /// KernelFunction on each pair of columns in the data matrix.
    ///
    /// @note Can not handle NaNs. 
    ///
    Kernel(const MatrixLookupWeighted& data, const KernelFunction& kf); 

    ///
    /// The new kernel is created using selected features @a
    /// index. Kernel will own its underlying data and delete it in
    /// destructor.
    ///
    Kernel(const Kernel& kernel, const std::vector<size_t>& index);

    ///
    ///   Destructor
    ///
    virtual ~Kernel(void);

    ///
    /// @return element at position (\a row, \a column) of the Kernel
    /// matrix
    ///
    virtual double operator()(const size_t row, const size_t column) const=0;

    ///
    /// @return const reference to the underlying data.
    ///
    inline const DataLookup2D& data(void) const { return *data_; }

    ///
    /// @brief number of samples 
    ///
    inline size_t size(void) const { return data_->columns(); } 

    ///
    /// Calculates the scalar product (using the KernelFunction)
    /// between vector @a vec and the \f$ i \f$ th column in the data
    /// matrix.
    ///   
    double element(const DataLookup1D& vec, const size_t i) const;

    ///
    /// Calculates the weighted scalar product (using the
    /// KernelFunction) between vector @a vec and the \f$ i \f$ th column
    /// in the data matrix. Using a weight vector with all elements
    /// equal to unity yields same result as the non-weighted version
    /// above.
    ///
    double element(const DataLookupWeighted1D& vec, const size_t i) const;

    ///
    /// Created Kernel is built from selected features in data. The
    /// @a index corresponds to which rows in data to use for the
    /// calculation of the returned Kernel.
    /// 
    /// @return Dynamically allocated Kernel based on selected features
    ///
    /// @Note Returns a dynamically allocated Kernel, which has
    /// to be deleted by the caller to avoid memory leaks.
    ///
    virtual const Kernel* selected(const std::vector<size_t>& index) const=0;

    ///
    /// @return true if kernel is calculated using weights
    ///
    inline bool weighted(void) const { return data_w_; }

  protected:
    /// underlyung data
    const DataLookup2D* data_;
    /// same as data_ if weifghted otherwise a NULL pointer
    const MatrixLookupWeighted* data_w_;
    /// type of Kernel Function e.g. Gaussian (aka RBF)
    const KernelFunction* kf_;
    /// if true we own data and will delete it in destructor
    const bool data_owner_;
    /// if true we own data_w and will delete it in destructor
    bool weight_owner_;

  private:
    ///
    /// Copy constructor (not implemented)
    ///
    Kernel(const Kernel&);

    const Kernel& operator=(const Kernel&);

  }; // class Kernel

}} // of namespace classifier and namespace theplu

#endif