source: trunk/yat/classifier/MatrixLookup.h @ 2223

#ifndef _theplu_yat_classifier_matrix_lookup_ 
#define _theplu_yat_classifier_matrix_lookup_ 

// $Id$

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

  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 3 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 yat. If not, see <http://www.gnu.org/licenses/>.
*/

#include "yat/utility/Container2DIterator.h"
#include "yat/utility/deprecate.h"
#include "yat/utility/Index.h"
#include "yat/utility/iterator_traits.h"
#include "yat/utility/Matrix.h"
#include "yat/utility/SmartPtr.h"

#include <boost/iterator/permutation_iterator.hpp>

#include <iosfwd>
#include <vector>

namespace theplu {
namespace yat {
namespace classifier {  

  ///
  /// @brief General view into utility::Matrix
  ///
  /// 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 utility::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 utility::Matrix, respectively. This design
  /// allow for fast creation of sub-matrices, which is a common
  /// operation in most traning/validation procedures. The views are
  /// const views in the sense that they cannot modify underlying
  /// utility::Matrix.
  ///
  /// A MatrixLookup can be created directly from a utility::Matrix or from 
  /// another MatrixLookup. In the latter case, the resulting
  /// MatrixLookup is looking directly into the underlying utility::Matrix to
  /// avoid multiple lookups.
  ///
  /// There is a possibility to set the MatrixLookup as owner of the
  /// underlying utility::Matrix. This implies that underlying data is deleted
  /// in destructor of MatrixLookup, but only if there is no other
  /// owner of the underlying data. 
  ///
  /// \see MatrixLookupWeighted
  ///
  class MatrixLookup
  {
  public:
    /**
       value_type is double

       \since New in yat 0.5
     */
    typedef utility::Matrix::value_type value_type;

    /**
       const_reference type is const double&

       \since New in yat 0.5
     */
    typedef utility::Matrix::const_reference const_reference;

    /// 'Read Only' iterator
    typedef utility::Container2DIterator<const MatrixLookup, value_type, 
                                         const_reference>
    const_iterator;

    /**
       'Read only' iterator used to iterate over a column
     */
    typedef boost::permutation_iterator<utility::Matrix::const_column_iterator,
                                        utility::Index::const_iterator> 
    const_column_iterator;

    /**
       'Read only' iterator used to iterate over a row
     */
    typedef const_column_iterator const_row_iterator;

    ///
    /// Constructor creating a lookup into the entire @a matrix. 
    /// \param matrix underlying matrix
    /// @param own if true MatrixLookup owns its underlying @a matrix
    ///
    /// @note If \a own is true and \a matrix is already owned by some
    /// other object, this will lead to \a matrix having multiple
    /// owners without the owners being aware of each
    /// other. Consequently multiple deletion will occur. 
    ///
    /// @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 utility::Index& row, 
                 const utility::Index& 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.
    ///
    /// \deprecated Provided for backgroundColor compatibility with
    /// the 0.6 API. Use MatrixLookup(const utility::Matrix&, const
    /// utility::Index&, const utility::Index&)
    ///
    MatrixLookup(const utility::Matrix& matrix, 
                 const utility::Index& index, 
                 const bool row_vectors) YAT_DEPRECATE;

    ///
    /// @brief Copy constructor.
    ///
    /// If \a other is owner of underlying data, constructed
    /// MatrixLookup will also be set as owner of underlying data.
    ///
    /// @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& other);

    ///
    /// @brief Create 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.
    ///
    /// If \a ml is owner of underlying data, constructed
    /// MatrixLookup will also be set as owner of underlying data.
    ///
    /// The @a row and @a column define what sub-matrix to look into,
    /// in other words, the created MatrixLookup will fullfill the
    /// following: MatrixLookup(i,j)=ml(row[i],column[j]). 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.
    ///
    /// If \a ml is owner of underlying data, constructed
    /// MatrixLookup will also be set as owner of underlying data.
    ///
    /// @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 utility::Index& row, 
                 const utility::Index& 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:
    /// MatrixLookup(i,j)=ml(i,index[j])
    ///
    /// 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$
    ///
    /// If \a ml is owner of underlying data, constructed
    /// MatrixLookup will also be set as owner of underlying data.
    ///
    /// @note If underlying matrix goes out of scope or is deleted, the
    /// MatrixLookup becomes invalid and the result of further use is
    /// undefined.
    ///
    /// \deprecated Provided for backgroundColor compatibility with
    /// the 0.6 API. Use MatrixLookup(const MatrixLookup&, const
    /// utility::Index&, const utility::Index&)
    ///
    MatrixLookup(const MatrixLookup& ml, const utility::Index&, 
                 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 utility::Matrix is created from
    /// the stream using utility::Matrix(std::istream&). The
    /// constructed MatrixLookup will be owner of the underlying
    /// matrix.
    ///
    /// @see Matrix(istream&) for details.
    ///
    MatrixLookup(std::istream&, char sep='\0');

    ///
    /// @brief Destructor. 
    ///
    /// If ownership is set true and there is no other owner of
    /// underlying data, underlying data is deleted.
    ///
    virtual ~MatrixLookup();

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

    /**
       \return number of columns
    */
    size_t columns(void) 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;

    /**
       \return number of rows
    */
    size_t rows(void) const;

    ///
    /// @return false
    ///
    bool weighted(void) const;

    ///
    /// Access operator
    ///
    /// @return element 
    ///
    const_reference operator()(size_t row, size_t column) const;

    ///
    /// @brief assigment operator
    ///
    /// Does only change MatrixLookup not the underlying matrix
    /// object. However if the MatrixLookup is owner (and the only owner)
    /// of its underlying
    /// matrix, that matrix will be deleted here.
    ///
    const MatrixLookup& operator=(const MatrixLookup&);
    
  private:
    friend class MatrixLookupWeighted;

    utility::Index column_index_;
    typedef utility::SmartPtr<const utility::Matrix> MatrixP;
    MatrixP data_;
    utility::Index row_index_;

    // for assertions
    bool validate(void) const;
  };  
  
  ///
  /// The output operator MatrixLookup
  ///
  /// \relates MatrixLookup
  ///
  std::ostream& operator<< (std::ostream& s, const MatrixLookup&);

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

#endif