source: trunk/lib/classifier/KernelLookup.h @ 545

// $Id: KernelLookup.h 545 2006-03-06 13:35:45Z peter $

#ifndef _theplu_classifier_kernel_lookup_
#define _theplu_classifier_kernel_lookup_

#include <c++_tools/classifier/Kernel.h>
#include <c++_tools/classifier/DataLookup2D.h>
#include <vector>

namespace theplu {
namespace classifier {

  class KernelFunction;

  ///
  /// @brief View into sub Kernel
  ///
  class KernelLookup : public DataLookup2D 
  {

  public:
    
    ///
    /// @brief Constructor from a Kernel
    ///
    /// @parameter own if true @a kernel is deleted in destructor,
    /// i.e., it must be dynamically allocated.
    ///
    /// @note If underlying Kernel goes out of scope or is deleted, the
    /// returned pointer becomes invalid and the result of further use is
    /// undefined.
    ///
    KernelLookup(const Kernel& kernel, const bool own=false);

    /// 
    /// Constructor creating a subKernel. The
    /// \f$i\f$th row in constructed lookup is identical to row number
    /// row[i] in matrix. The \f$i\f$th column in constructed lookup
    /// is identical to column number column[i] in matrix.
    ///
    /// @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);
    
    /// 
    /// Copy constructor
    ///
    KernelLookup(const KernelLookup&);


    /// 
    /// Contructor building a sub-KernelLookup from a KernelLookup
    /// defined by row index vector and column index vector. The
    /// resulting KernelLookup is independent of the old KernelLookup,
    /// but is undefined in case underlying Kernel is destroyed.
    ///
    /// @note For training usage row index shall always be equal to
    /// column index.
    ///
    KernelLookup(const KernelLookup& kernel, const std::vector<size_t>& row, 
                 const std::vector<size_t>& column);
    
    ///
    /// @brief Destructor
    ///
    /// Deletes underlying Kernel if KernelLookup owns it. 
    ///
    virtual ~KernelLookup(void);


    ///
    /// @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* 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.
    ///
    /// @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 element at position (\a row, \a column) in the Kernel
    /// matrix
    ///
    inline double operator()(const size_t row,const size_t column) const
    { return (*kernel_)(row_index_[row],column_index_[column]); }

    ///
    /// Each column in returned MatrixLook corresponds to the column
    /// in KernelLookup.
    ///
    /// @Note Returns a dynamically allocated MatrixLookup2D, which has
    /// to be deleted by the caller to avoid memory leaks.
    ///
    inline const MatrixLookup* data(void) const
    { return new MatrixLookup(kernel_->data(),column_index_); }


    ///
    /// @todo doc
    ///
    inline double element(const DataLookup1D& vec, const size_t i) const
    { return kernel_->element(vec, row_index_[i]); }

    ///
    /// @todo doc
    ///
    inline double element(const DataLookup1D& vec, const DataLookup1D& w, 
                          const size_t i) const
    { return kernel_->element(vec, w, row_index_[i]); }

    ///
    /// @todo doc
    ///
    /// @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>&) const;
    
    ///
    /// @return true if underlying Kernel is weighted
    ///
    inline bool weighted(void) const { return kernel_->weighted(); }

    ///
    /// @todo doc
    ///
    /// @Note Returns a dynamically allocated KernelLookup, which has
    /// to be deleted by the caller to avoid memory leaks.
    ///
    const MatrixLookup* weights(void) const;


  private:
    ///
    /// Default constructor. Not implemented.
    ///
    KernelLookup(void);

    const Kernel* kernel_;

  }; // class KernelLookup

}} // of namespace classifier and namespace theplu

#endif