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

#ifndef _theplu_yat_classifier_kernel_
#define _theplu_yat_classifier_kernel_

// $Id$

/*
  Copyright (C) 2005 Jari Häkkinen, Peter Johansson
  Copyright (C) 2006 Jari Häkkinen, Peter Johansson, Markus Ringnér
  Copyright (C) 2007 Jari Häkkinen, Peter Johansson
  Copyright (C) 2008 Jari Häkkinen, 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 "KernelFunction.h"

#include <cstddef>
#include <vector>

namespace theplu {
namespace yat {
namespace classifier {

  class MatrixLookup;
  class MatrixLookupWeighted;

  ///
  ///  @brief Interface 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 to
  ///  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. 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.
    /// If @a own is set to true, Kernel is owner of underlying data.
    ///
    /// @note Can not handle NaNs. To deal with missing values use
    /// constructor taking MatrixLookupWeighted.
    ///
    Kernel(const MatrixLookup& data, const KernelFunction& kf, 
           const bool own=false); 

    ///
    /// 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.
    /// If @a own is set to true, Kernel is owner of underlying data.
    ///
    Kernel(const MatrixLookupWeighted& data, const KernelFunction& kf, 
           const bool own=false); 

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

    ///
    /// @brief Destructor
    ///
    /// If Kernel is owner of underlying data and Kernel is the last
    /// owner, underlying data is deleted.
    ///
    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.
    ///
    /// \throw if data is weighted 
    ///
    const MatrixLookup& data(void) const;

    ///
    /// @return const reference to the underlying data.
    ///
    /// \throw if data is unweighted 
    ///
    const MatrixLookupWeighted& data_weighted(void) const;

    ///
    /// 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;

    ///
    /// An interface for making new classifier objects. This function
    /// allows for specification at run-time of which kernel to
    /// instatiate (see 'Prototype' in Design Patterns).
    ///
    /// @note Returns a dynamically allocated Kernel, which has
    /// to be deleted by the caller to avoid memory leaks.
    ///
    virtual const Kernel* make_kernel(const MatrixLookup&, const bool) const=0;


    ///
    /// An interface for making new classifier objects. This function
    /// allows for specification at run-time of which kernel to
    /// instatiate (see 'Prototype' in Design Patterns).
    ///
    /// @note Returns a dynamically allocated Kernel, which has
    /// to be deleted by the caller to avoid memory leaks.
    ///
    virtual const Kernel* make_kernel(const MatrixLookupWeighted&, 
                                      const bool own=false) const=0;


    /**
       \brief number of samples 
    */
    size_t size(void) const;

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

  protected:
    /// underlying data
    const MatrixLookup* ml_;
    /// same as data_ if weifghted otherwise a NULL pointer
    const MatrixLookupWeighted* mlw_;
    /// type of Kernel Function e.g. Gaussian (aka RBF)
    const KernelFunction* kf_;

    ///
    /// pointer telling how many owners to underlying data
    /// (data_). NULL if this is not an owner.
    ///
    unsigned int* ref_count_;

    ///
    /// pointer telling how many owners to underlying weights
    /// (data_w_). NULL if this is not an owner.
    ///
    unsigned int* ref_count_w_;

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

    const Kernel& operator=(const Kernel&);

  }; // class Kernel

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

#endif