source: trunk/c++_tools/classifier/MatrixLookup.h @ 675

#ifndef _theplu_classifier_matrix_lookup_ 
#define _theplu_classifier_matrix_lookup_ 

// $Id$

/*
  Copyright (C) The authors contributing to this file.

  This file is part of the yat library, http://lev.thep.lu.se/trac/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 "yat/classifier/DataLookup2D.h"
#include "yat/utility/matrix.h"

#include <cassert>

namespace theplu {
namespace classifier {  

  

  ///
  /// MatrixLookups can be used to create lookups/views into matrices
  /// in a more general way than the views supported in the matrix
  /// class. The object does not contain any data, but only a pointer
  /// to a matrix and row and columns incices defining which
  /// sub-matrix to look into.  Each row and each column corresponds
  /// to a row and a column in the Kernel, respectively. This design
  /// allow for fast creation of sub-matrices, which is a common
  /// operation in most traning/validation procedures.
  ///
  /// A MatrixLookup can be created directly from a matrix or from an
  /// other MatrixLookup. In the latter case, the resulting
  /// MatrixLookup is looking directly into the underlying matrix to
  /// avoid multiple lookups.
  ///
  /// There is a possibility to set the MatrixLookup as owner of the
  /// underlying matrix. 
  ///
  class MatrixLookup : public DataLookup2D
  {
  
  public:


    ///
    /// Constructor creating a lookup into the entire @a matrix. 
    /// @param own if true MatrixLookup owns its underlying @a matrix
    ///
    /// @note If @a matrix goes out of scope or is deleted, the
    /// MatrixLookup becomes invalid and the result of further use is
    /// undefined.
    ///
    MatrixLookup(const utility::matrix& matrix, const bool own=false);

    ///
    /// 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 MatrixLookup will fullfill the
    /// following: \f$ MatrixLookup(i,j)=matrix(row[i],column[j])
    /// \f$. This also means that number of rows in created
    /// MatrixLookup is equal to size of vector @a row, and number of
    /// columns is equal to size of vector @a column.
    ///
    /// @note If @a matrix goes out of scope or is deleted, the
    /// MatrixLookup becomes invalid and the result of further use is
    /// undefined.
    ///
    MatrixLookup(const utility::matrix& matrix, const std::vector<size_t>& row, 
                 const std::vector<size_t>& column);

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

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

    ///
    /// Creates a sub-MatrixLookup. The Lookup is independent of
    /// MatrixLookup @a ml. The MatrixLookup 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 MatrixLookup will fullfill the
    /// following: \f$ MatrixLookup(i,j)=ml(row[i],column[j]) \f$. This
    /// also means that number of rows in created MatrixLookup 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
    /// MatrixLookup becomes invalid and the result of further use is
    /// undefined.
    ///
    MatrixLookup(const MatrixLookup& 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 MatrixLookup is created to look directly into the
    /// underlying matrix to avoid multiple lookups.
    ///
    /// If @a row_vectors is true the new MatrixLookup will consist
    /// of the row vectors defined by @a index. This means that the
    /// created MatrixLookup will fullfill:
    /// \f$ MatrixLookup(i,j)=ml(i,index[j])\f$
    ///
    /// If @a row_vectors is false the new MatrixLookup will consist
    /// of the rolumn vectors defined by @a index. This means that the
    /// created MatrixLookup will fullfill:
    /// \f$ MatrixLookup(i,j) = ml(index[i],j) \f$
    ///
    /// @note If underlying matrix goes out of scope or is deleted, the
    /// MatrixLookup becomes invalid and the result of further use is
    /// undefined.
    ///
    MatrixLookup(const MatrixLookup& ml, const std::vector<size_t>&, 
                 const bool row_vectors);

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

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

    ///
    /// Destructor. 
    ///
    virtual ~MatrixLookup();

    /**
       the new MatrixLookup will consist of the rolumn vectors
       defined by @a index. This means that the returned MatrixLookup
       will fullfill: \f$ returned(i,j) = original(index[i],j) \f$

       @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 MatrixLookup* selected(const std::vector<size_t>&) const;

    ///
    /// The created MatrixLookup corresponds to all rows and the
    /// columns defined by @a index in the original MatrixLookup. The
    /// created MatrixLookup will fullfill:
    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
    ///
    /// @return pointer to sub-Lookup of the MatrixLookup
    ///
    /// @note If underlying matrix goes out of scope or is deleted, the
    /// returned pointer becomes invalid and the result of further use is
    /// undefined.
    ///
    /// @Note Returns a dynamically allocated DataLookup2D, which has
    /// to be deleted by the caller to avoid memory leaks.
    ///
    const MatrixLookup* training_data(const std::vector<size_t>& index) const;
    
    ///
    /// The created MatrixLookup corresponds to all rows and the
    /// columns defined by @a index in the original MatrixLookup. The
    /// created MatrixLookup will fullfill:
    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
    ///
    /// @return pointer to sub-Lookup of the MatrixLookup
    ///
    /// @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 MatrixLookup* validation_data(const std::vector<size_t>&,
                                        const std::vector<size_t>&) const;
    ///
    /// @return false
    ///
    bool weighted(void) const;

    ///
    /// Access operator
    ///
    /// @return element 
    ///
    inline double operator()(const size_t row, const size_t column) const
    { 
      assert(row<rows());
      assert(column<columns());
      return (*data_)(row_index_[row], column_index_[column]); 
    }

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

}} // of namespace classifier and namespace theplu

#endif