source: trunk/c++_tools/classifier/MatrixLookupWeighted.h @ 624

#ifndef _theplu_classifier_matrix_lookup_weighted_ 
#define _theplu_classifier_matrix_lookup_weighted_ 

// $Id$

#include <c++_tools/classifier/DataLookup2D.h>
#include <c++_tools/utility/matrix.h>

#include <cassert>

namespace theplu {
namespace classifier {  

  
  ///
  /// A MatrixLookupWeighted is very similar to a MatrixLookup, but
  /// contains a pointer to a weight matrix as well meaning each data
  /// element is associated to weight.
  ///
  /// A MatrixLookupWeighted can be created directly from a matrix or
  /// from an other MatrixLookupWeighted. In the latter case, the
  /// resulting MatrixLookupWeighted is looking directly into the
  /// underlying matrix to avoid multiple lookups.
  ///
  /// There is a possibility to set the MatrixLookupWeighted as owner
  /// of the underlying matrices (data and weight). In that case the
  /// underlying matrix will be destroyed in the
  /// destructor. Consequently, the underlying matricis must have been
  /// dynamically allocated and no other MatrixLookupWeighted can own
  /// the matrices.
  ///
  /// @todo add on weight part
  ///
  class MatrixLookupWeighted : public DataLookup2D
  {
  
  public:


    ///
    /// Constructor creating a lookup into the entire @a matrix. 
    ///
    /// @note If @a matrix or @a weights goes out of scope or is
    /// deleted, the MatrixLookupWeighted becomes invalid and the
    /// result of further use is undefined.
    ///
    MatrixLookupWeighted(const utility::matrix& matrix, 
                         const utility::matrix& weights);

    ///
    /// Constructor creating a lookup into a sub-matrix of @a matrix.
    /// The @a row and @a column define what sub-matrix to look into,
    /// in other words, the created MatrixLookupWeighted will fullfill
    /// the following: \f$
    /// MatrixLookupWeighted(i,j)=matrix(row[i],column[j])
    /// weights(row[i],column[j])\f$. This also means that number of
    /// rows in created MatrixLookupWeighted is equal to size of
    /// vector @a row, and number of columns is equal to size of
    /// vector @a column.
    ///
    /// @note If @a matrix or @a weights goes out of scope or is deleted, the
    /// MatrixLookupWeighted becomes invalid and the result of further use is
    /// undefined.
    ///
    MatrixLookupWeighted(const utility::matrix& matrix, 
                         const utility::matrix& weights, 
                         const std::vector<size_t>& row, 
                         const std::vector<size_t>& column);

    ///
    /// Constructor creating a lookup into a sub-matrix of @matrix.
    ///
    /// If @a row_vectors is true the new MatrixLookupWeighted will be
    /// consist of the row vectors defined by @a index. This means
    /// that the created MatrixLookupWeighted will fullfill: \f$
    /// MatrixLookupWeighted(i,j)=matrix(i,index[j])*weights(i,index[j])
    /// \f$
    ///
    /// If @a row_vectors is false the new MatrixLookupWeighted will be consist
    /// of the rolumn vectors defined by @a index. This means that the
    /// created MatrixLookupWeighted will fullfill:
    /// \f$ MatrixLookupWeighted(i,j)=matrix(index[i],j) \f$
    ///
    /// @note If @a matrix or @a weights goes out of scope or is
    /// deleted, the MatrixLookupWeighted becomes invalid and the
    /// result of further use is undefined.
    ///
    MatrixLookupWeighted(const utility::matrix& matrix, 
                         const utility::matrix& weights, 
                         const std::vector<size_t>& index, 
                         const bool row_vectors);

    ///
    /// @brief
    ///
    /// @note If underlying matrix goes out of scope or is deleted, the
    /// MatrixLookupWeighted becomes invalid and the result of further use is
    /// undefined.
    ///
    //MatrixLookupWeighted(const MatrixLookup&, const MatrixLookup);

    ///
    /// @brief Copy constructor.
    ///
    /// @note If underlying matrix goes out of scope or is deleted, the
    /// MatrixLookupWeighted becomes invalid and the result of further use is
    /// undefined.
    ///
    MatrixLookupWeighted(const MatrixLookupWeighted&);

    ///
    /// Creates a sub-MatrixLookupWeighted. The Lookup is independent of
    /// MatrixLookupWeighted @a ml. The MatrixLookupWeighted is created to look
    /// directly into the underlying matrix to avoid multiple lookups.
    ///
    /// The @a row and @a column define what sub-matrix to look into,
    /// in other words, the created MatrixLookupWeighted will fullfill the
    /// following: \f$ MatrixLookupWeighted(i,j)=ml(row[i],column[j]) \f$. This
    /// also means that number of rows in created MatrixLookupWeighted is
    /// equal to size of vector @a row, and number of columns is equal
    /// to size of vector @a column.
    ///
    /// @note If underlying matrix goes out of scope or is deleted, the
    /// MatrixLookupWeighted becomes invalid and the result of further use is
    /// undefined.
    ///
    MatrixLookupWeighted(const MatrixLookupWeighted& ml, 
                         const std::vector<size_t>& row, 
                         const std::vector<size_t>& column);

    ///
    /// Constructor creating a lookup into a sub-matrix of
    /// @a ml. The MatrixLookupWeighted is created to look directly into the
    /// underlying matrix to avoid multiple lookups.
    ///
    /// If @a row_vectors is true the new MatrixLookupWeighted will be consist
    /// of the row vectors defined by @a index. This means that the
    /// created MatrixLookupWeighted will fullfill:
    /// \f$ MatrixLookupWeighted(i,j)=ml(i,index[j])\f$
    ///
    /// If @a row_vectors is false the new MatrixLookupWeighted will be consist
    /// of the rolumn vectors defined by @a index. This means that the
    /// created MatrixLookupWeighted will fullfill:
    /// \f$ MatrixLookupWeighted(i,j) = ml(index[i],j) \f$
    ///
    /// @note If underlying matrix goes out of scope or is deleted, the
    /// MatrixLookupWeighted becomes invalid and the result of further use is
    /// undefined.
    ///
    MatrixLookupWeighted(const MatrixLookupWeighted& ml, 
                         const std::vector<size_t>&, 
                         const bool row_vectors);

    ///
    /// Constructor creating a MatrixLookupWeighted with @a rows rows, @a
    /// columns columns, and all values are set to @a value. Created
    /// MatrixLookupWeighted owns its underlying matrix.
    ///
    MatrixLookupWeighted(const size_t rows, const size_t columns, 
                         const double value=0, const double weight=1);

    ///
    /// @brief The istream constructor.
    ///
    /// In construction the underlying matrix is created from
    /// stream. The MatrixLookupWeighted will be owner of the underlying
    /// matrix.
    ///
    /// @see matrix(istream&) for details.
    ///
    MatrixLookupWeighted(std::istream&, char sep='\0');

    ///
    /// Destructor. If MatrixLookup is owner of underlying matrix, the
    /// matrix is destroyed.
    ///
    virtual ~MatrixLookupWeighted();

    ///
    /// @return data value of element (@a row, @a column)
    ///
    inline double data(size_t row, size_t column) const 
    { return (*data_)(row_index_[row], column_index_[column]); }

    ///
    /// @todo doc
    ///
    const MatrixLookupWeighted* selected(const std::vector<size_t>& i) const;

    ///
    /// The created MatrixLookupWeighted corresponds to all rows and the
    /// columns defined by @a index in the original MatrixLookupWeighted. The
    /// created MatrixLookupWeighted will fullfill:
    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
    ///
    /// @return pointer to sub-Lookup of the MatrixLookupWeighted
    ///
    /// @note If underlying matrix goes out of scope or is deleted, the
    /// returned pointer becomes invalid and the result of further use is
    /// undefined.
    ///
    const MatrixLookupWeighted* 
    training_data(const std::vector<size_t>& index) const;
    
    ///
    /// The created MatrixLookupWeighted corresponds to rows defined
    /// by @a features and columns defined by @a samples in the
    /// original MatrixLookupWeighted. The created
    /// MatrixLookupWeighted will fullfill: 
    /// \f$ novel_ml(i,j)=original(features[i],samples[j]) \f$.
    ///
    /// @return pointer to sub-Lookup of the MatrixLookupWeighted
    ///
    /// @note If underlying matrix goes out of scope or is deleted, the
    /// returned pointer becomes invalid and the result of further use is
    /// undefined.
    ///
    const MatrixLookupWeighted* 
    training_data(const std::vector<size_t>& features, 
                  const std::vector<size_t>& samples) const;
    
    ///
    /// The created MatrixLookupWeighted corresponds to all rows and the
    /// columns defined by @a index in the original MatrixLookupWeighted. The
    /// created MatrixLookupWeighted will fullfill:
    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
    ///
    /// @return pointer to sub-Lookup of the MatrixLookupWeighted
    ///
    /// @note If underlying matrix goes out of scope or is deleted, the
    /// returned pointer becomes invalid and the result of further use is
    /// undefined.
    ///
    const MatrixLookupWeighted* validation_data(const std::vector<size_t>&,
                                        const std::vector<size_t>&) const;

    ///
    /// The created MatrixLookupWeighted corresponds to rows defined
    /// by @a features and columns defined by @a val in the original
    /// MatrixLookupWeighted. The created MatrixLookupWeighted will
    /// fullfill: \f$ novel_ml(i,j)=original(features[i],val[j]) \f$.
    ///
    /// @return pointer to sub-Lookup of the MatrixLookupWeighted
    ///
    /// @note If underlying matrix goes out of scope or is deleted, the
    /// returned pointer becomes invalid and the result of further use is
    /// undefined.
    ///
    const MatrixLookupWeighted* 
    validation_data(const std::vector<size_t>& features,
                    const std::vector<size_t>& training,
                    const std::vector<size_t>& val) const;

    ///
    /// @return weight value of element (@a row, @a column)
    ///
    inline double weight(size_t row, size_t column) const 
    { return (*weights_)(row_index_[row], column_index_[column]); }

    ///
    /// Access operator
    ///
    /// @return weight * data for element \f$ i j\f$ 
    ///
    inline double operator()(const size_t row, const size_t column) const
    { 
      return data(row,column)*weight(row,column);
    }

    ///
    /// @brief assigment operator
    ///
    /// Does only change MatrixLookupWeighted not the underlying matrix
    /// object. However if the MatrixLookupWeighted is owner of its underlying
    /// matrix, that matrix will be deleted here.
    ///
    const MatrixLookupWeighted& operator=(const MatrixLookupWeighted&);
    
  private:
    const utility::matrix* data_;
    const utility::matrix* weights_;
  };  
  
  ///
  /// The output operator MatrixLookupWeighted 
  ///
  std::ostream& operator<< (std::ostream& s, const MatrixLookupWeighted&);

}} // of namespace classifier and namespace theplu

#endif