source: branches/0.12-stable/yat/classifier/MatrixLookupWeighted.h @ 3275

#ifndef _theplu_yat_classifier_matrix_lookup_weighted_
#define _theplu_yat_classifier_matrix_lookup_weighted_

// $Id$

/*
  Copyright (C) 2006 Jari Häkkinen, Peter Johansson, Markus Ringnér
  Copyright (C) 2007, 2008 Jari Häkkinen, Peter Johansson
  Copyright (C) 2009, 2010, 2012 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/DataWeight.h"
#include "yat/utility/deprecate.h"
#include "yat/utility/Index.h"
#include "yat/utility/MatrixWeighted.h"
#include "yat/utility/StrideIterator.h"

#include <boost/iterator/permutation_iterator.hpp>
#include <boost/shared_ptr.hpp>

#include <iosfwd>
#include <utility>
#include <vector>

namespace theplu {
namespace yat {
namespace classifier {

  class MatrixLookup;

  ///
  /// @brief General view into utility::MatrixWeighted
  ///
  /// A MatrixLookupWeighted can be created directly from a
  /// utility::MatrixWeighted or from another 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 utility::MatrixWeighted.  This implies that
  /// underlying data is deleted in destructor of
  /// MatrixLookupWeighted, but only if there is no other owner of the
  /// underlying data.
  ///
  /// \see MatrixLookup
  ///
  class MatrixLookupWeighted
  {
  public:
    /**
       value_type is DataWeight

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

    /**
       const_reference type is const DataWeight

       \since New in yat 0.5
     */
    typedef const utility::DataWeight& const_reference;

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

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

    /**
       'Read only' iterator used to iterate over a row
     */
    typedef boost::permutation_iterator<
      utility::MatrixWeighted::const_row_iterator,
      utility::Index::const_iterator> const_row_iterator;

    /**
       \brief Create a lookup into \a matrix.

       The created lookup, mlw, will fullfil: mlw(i,j) =
       matrix(rows(i), columns(j))
     */
    MatrixLookupWeighted(const utility::MatrixWeighted& matrix,
                         const utility::Index& rows,
                         const utility::Index& columns);

    /**
       \brief Create a lookup into entire \a matrix.
     */
    explicit MatrixLookupWeighted(const utility::MatrixWeighted& matrix,
                                  bool owner=false);

    /**
       Constructor creating a MatrixLookupWeighted from a MatrixLookup. A
       weight matrix with unitary weights are created internally.

       \note no check for nan is performed.

       @note from yat 0.5 data is copied and further modifications in
       \a matrix will not be reflected in MatrixLookupWeighted.
    */
    explicit MatrixLookupWeighted(const MatrixLookup& matrix);


    ///
    /// @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
    /// MatrixLookupWeighted becomes invalid and the result of further use is
    /// undefined.
    ///
    MatrixLookupWeighted(const MatrixLookupWeighted& other);

    ///
    /// 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.
    ///
    /// 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
    /// MatrixLookupWeighted becomes invalid and the result of further use is
    /// undefined.
    ///
    MatrixLookupWeighted(const MatrixLookupWeighted& ml,
                         const utility::Index& row,
                         const utility::Index& 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 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 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$
    ///
    /// 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
    /// MatrixLookupWeighted becomes invalid and the result of further use is
    /// undefined.
    ///
    /// \deprecated Provided for backward compatibility with the 0.6
    /// API. Use MatrixLookupWeighted(const MatrixLookupWeighted&,
    /// const utility::Index&, const utility::Index&)
    ///
    MatrixLookupWeighted(const MatrixLookupWeighted& ml,
                         const utility::Index&,
                         const bool row_vectors) YAT_DEPRECATE;

    ///
    /// 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 utility::MatrixWeighted(istream&) for details.
    ///
    MatrixLookupWeighted(std::istream&, char sep='\0');

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

    /**
       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 data value of element (@a row, @a column)
    ///
    double data(size_t row, size_t column) 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 weight value of element (@a row, @a column)
    ///
    double weight(size_t row, size_t column) const;

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

    ///
    /// Access operator
    ///
    /// @return data-weight pair (@a row, @a column)
    ///
    const_reference operator()(const size_t row, const size_t column) const;

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

  private:
    typedef boost::shared_ptr<const utility::MatrixWeighted> MatrixWP;
    utility::Index column_index_;
    MatrixWP data_;
    utility::Index row_index_;

    // for assertions
    bool validate(void) const;
  };

  ///
  /// The output operator MatrixLookupWeighted
  ///
  /// For eacd data element data(i,j) is printed except those being
  /// associated with a zero weight for which nothing is printed.
  ///
  /// \relates MatrixLookupWeighted
  ///
  std::ostream& operator<< (std::ostream& s, const MatrixLookupWeighted&);

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

#endif