source: trunk/yat/classifier/KernelLookup.h @ 1125

#ifndef _theplu_yat_classifier_kernel_lookup_
#define _theplu_yat_classifier_kernel_lookup_

// $Id$

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

  This file is part of the yat library, http://trac.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 "Kernel.h"
#include "DataLookup2D.h"
#include "MatrixLookup.h"
#include "yat/utility/Container2DIterator.h"
#include "yat/utility/iterator_traits.h"
#include "yat/utility/StrideIterator.h"


#include <vector>

namespace theplu {
namespace yat {
namespace classifier {

  class KernelFunction;

  ///
  /// @brief Lookup into Kernel
  ///
  /// This is the KernelLookup class to be used together with kernel
  /// methods such as Support Vector Machines (SVM). The class does
  /// not contain any data or values, but rather is a lookup into a
  /// Kernel object. Each row and each column corresponds to a row and
  /// a column in the Kernel, respectively. This design allow for fast
  /// creation of sub-kernels, which is a common operation in most
  /// traning/validation procedures.
  ///
  /// A KernelLookup can be created directly from a Kernel or from an
  /// other KernelLookup. In the latter case, the resulting
  /// KernelLookup is looking directly into the underlying Kernel to
  /// avoid multiple lookups.
  ///
  /// There is a possibility to set the KernelLookup as owner of the
  /// underlying kernel. This implies that underlying kernel is deleted
  /// in destructor of MatrixLookup, but only if there is no other
  /// owner of the underlying kernel. A reference counter is used to
  /// keep track of number of owners. Ownership is copied in copy
  /// constructors and assignments.
  ///
  class KernelLookup : public DataLookup2D 
  {

  public:
    /// 'Read Only' iterator
    typedef utility::StrideIterator<
    utility::Container2DIterator<const KernelLookup, const double, void, 
                                 const double> >
    const_iterator;

    /**
       'Read only' iterator intended to iterate over a column
     */
    typedef const_iterator const_column_iterator;

    /**
       'Read only' iterator intended to iterate over a row
     */
    typedef const_iterator const_row_iterator;

    ///
    /// @brief Constructor a Lookup into a Kernel
    ///
    /// Constructs a KernelLookup corresponding to the Kernel @a
    /// kernel. By default @a owner is set to false, which means
    /// KernelLookup does not own the underlying Kernel.
    ///
    /// @note If underlying Kernel goes out of scope or is deleted, the
    /// KernelLookup becomes invalid and the result of further use is
    /// undefined.
    ///
    /// @note Do not construct two KernelLookups from the same @a
    /// kernel with @a owner set to true because that will cause
    /// multiple deletion of @a kernel.
    ///
    KernelLookup(const Kernel& kernel, const bool owner=false);

    /// 
    /// @brief Constructing a Lookup into a subKernel
    ///
    /// Creating a Lookup into parts of the Kernel. In the created
    /// Lookup the element in the \f$ i \f$ th row in the \f$ j \f$ th
    /// column is identical to the element in row row[i] and columns
    /// column[j] in the underlying @a kernel. If @a owner is set to
    /// true yhe underlying @a kernel is destroyed in the destructor.
    ///
    /// @note If @a kernel goes out of scope or is deleted, the
    /// returned pointer becomes invalid and the result of further use is
    /// undefined.
    ///
    /// @note For training usage row index shall always be equal to
    /// column index.
    ///
    KernelLookup(const Kernel& kernel, const std::vector<size_t>& row, 
                 const std::vector<size_t>& column, const bool owner=false);

    /// 
    /// @brief Copy constructor. 
    ///
    /// A Lookup is created looking into the
    /// same underlying Kernel as @a kl is looking into. 
    ///
    /// If \a kl is owner of underlying data, constructed
    /// KernelLookup will also be set as owner of underlying data.
    ///
    KernelLookup(const KernelLookup& kl);


    /// 
    /// @brief Contructing a sub-KernelLookup. 
    ///
    /// Contructor building a sub-KernelLookup from a KernelLookup
    /// defined by row index vector and column index vector. In the
    /// created Lookup the element in the \f$ i \f$ th row in the
    /// \f$ j \f$ th column is identical to the element in row row[i] and
    /// columns column[j] in the copied @a kl. The resulting
    /// KernelLookup is independent of the old KernelLookup, but is
    /// undefined in case underlying Kernel is destroyed.
    ///
    /// If \a kl is owner of underlying data, constructed
    /// KernelLookup will also be set as owner of underlying data.
    ///
    /// @note For training usage row index shall always be equal to
    /// column index.
    ///
    KernelLookup(const KernelLookup& kl, const std::vector<size_t>& row, 
                 const std::vector<size_t>& column);

    ///
    /// Constructor taking the column (default) or row index vector as
    /// input. If @a row is false the created KernelLookup will have
    /// equally many rows as @a kernel.
    ///
    /// If \a kl is owner of underlying data, constructed
    /// KernelLookup will also be set as owner of underlying data.
    ///
    /// @note If underlying kernel goes out of scope or is deleted, the
    /// KernelLookup becomes invalid and the result of further use is
    /// undefined.
    ///
    KernelLookup(const KernelLookup& kernel, const std::vector<size_t>&, 
                 const bool row=false);

    ///
    /// @brief Destructor
    ///
    /// Deletes underlying Kernel if KernelLookup owns it and there is
    /// no other owner.
    ///
    virtual ~KernelLookup(void);

    /**
       Iterator iterates along a row. When end of row is reached it
       jumps to beginning of next row.

       \return const_iterator pointing to upper-left element.
     */
    const_iterator begin(void) const;

    /**
       Iterator iterates along a column.

       \return iterator pointing to first element of column \a i.
     */
    const_column_iterator begin_column(size_t) const;

    /**
       Iterator iterates along a column.

       \return const_iterator pointing to first element of column \a i.
     */
    const_row_iterator begin_row(size_t) const;

    ///
    /// Each column in returned DataLookup corresponds to the column
    /// in KernelLookup.
    ///
    /// \return data that KernelLookup is built upon.
    ///
    /// @note Returns a dynamically allocated MatrixLookup, which has
    /// to be deleted by the caller to avoid memory leaks.
    ///
    const DataLookup2D* data(void) const;

    /**
       Function to calculate a new Kernel element using the underlying
       KernelFunction. The value is calculated between @a vec and the
       data vector of the \a i th sample, in other words, the
       sample corresponding to the \a i th row.
    */
    double element(const DataLookup1D& vec, size_t i) const;

    /**
       Function to calculate a new Kernel element using the underlying
       KernelFunction. The value is calulated between @a vec and the
       data vector of the \f$ i \f$ th sample, in other words, the
       sample corresponding to the \f$ i \f$ th row or \f$ i \f$ th
       column. In case KernelLookup is a sub-Kernel and not symmetric,
       the kernel value is calculated between @a vec and the data
       vector corresponding to \f$ i \f$ th row.
    */
    double element(const DataLookupWeighted1D& vec, size_t i) const;

    /**
       \return const_iterator pointing to end of matrix
     */
    const_iterator end(void) const;

    /**
       \return const_iterator pointing to end of column \a i
     */
    const_column_iterator end_column(size_t) const;

    /**
       \return const_iterator pointing to end of row \a i
     */
    const_row_iterator end_row(size_t) const;

    /**
       Each element in returned KernelLookup is calculated using only
       selected features (defined by @a index). Each element
       corresponds to the same pair of samples as in the original
       KernelLookup.

       \note Returns a dynamically allocated KernelLookup, which has
       to be deleted by the caller to avoid memory leaks.
    */
    const KernelLookup* selected(const std::vector<size_t>& index) const;
    
    /**
       This function is useful when predicting on an independent data
       set using a kernel-based classifier. In returned KernelLookup
       column \f$ i \f$ corresponds to column \f$ i \f$ in @a
       data. Row \f$ i \f$ in returned KernelLookup corresponds to
       same sample as row \f$ i \f$ in @a this. In other words, this
       function returns a KernelLookup containing the kernel elements
       between the passed @a data and the internal underlying data @a
       this was built from.
    
       @note Returns a dynamically allocated DataLookup2D, which has
       to be deleted by the caller to avoid memory leaks.
    */
    const KernelLookup* test_kernel(const MatrixLookup& data) const;

    /**
       This function is useful when predicting on an independent data
       set using a kernel-based classifier. In returned KernelLookup
       column \f$ i \f$ corresponds to column \f$ i \f$ in @a
       data. Row \f$ i \f$ in returned KernelLookup corresponds to
       same sample as row \f$ i \f$ in @a this. In other words, this
       function returns a KernelLookup containing the kernel elements
       between the passed @a data and the internal underlying data @a
       this was built from.
    
       @note Returns a dynamically allocated DataLookup2D, which has
       to be deleted by the caller to avoid memory leaks.
    */
    const KernelLookup* test_kernel(const MatrixLookupWeighted& data) const;

    /**
       \brief Creates a sub-Kernel identical to the one created using
       KernelLookup(*this, train, train).
    
       \return pointer to dynamically allocated sub-Lookup of the
       KernelLookup
    
       \note Returns a dynamically allocated DataLookup2D, which has
       to be deleted by the caller to avoid memory leaks.
    */
    const KernelLookup* training_data(const std::vector<size_t>& train) const;

    /**
       In returned kernel each row corresponds to a training sample
       and each column corresponds to a validation sample. The created
       sub-KernelLookup is equivalent to using KernelLooup(*this,
       train, validation).
    
       \return sub-Lookup of the DataLookup2D
    
       \note Returns a dynamically allocated DataLookup2D, which has
       to be deleted by the caller to avoid memory leaks.
    */
    const KernelLookup* 
    validation_data(const std::vector<size_t>& train, 
                    const std::vector<size_t>& validation) const;

    /**
       \return true if underlying Kernel is weighted
    */
    bool weighted(void) const;

    /**
       \return element at position (\a row, \a column) in the Kernel
       matrix
    */
    double operator()(size_t row, size_t column) const;

  private:
    const KernelLookup& operator=(const KernelLookup&);

    const Kernel* kernel_;
    
  }; // class KernelLookup

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

#endif