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

Last change on this file since 1530 was 1530, checked in by Peter, 13 years ago

removing const in value_type - refs #444

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date ID
File size: 10.4 KB
RevLine 
[680]1#ifndef _theplu_yat_classifier_matrix_lookup_
2#define _theplu_yat_classifier_matrix_lookup_
[455]3
[616]4// $Id$
5
[675]6/*
[1275]7  Copyright (C) 2005 Peter Johansson, Markus Ringnér
8  Copyright (C) 2006 Jari Häkkinen, Peter Johansson, Markus Ringnér
[831]9  Copyright (C) 2007 Jari Häkkinen, Peter Johansson
[1275]10  Copyright (C) 2008 Peter Johansson
[455]11
[1437]12  This file is part of the yat library, http://dev.thep.lu.se/yat
[675]13
14  The yat library is free software; you can redistribute it and/or
15  modify it under the terms of the GNU General Public License as
[1486]16  published by the Free Software Foundation; either version 3 of the
[675]17  License, or (at your option) any later version.
18
19  The yat library is distributed in the hope that it will be useful,
20  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22  General Public License for more details.
23
24  You should have received a copy of the GNU General Public License
[1487]25  along with yat. If not, see <http://www.gnu.org/licenses/>.
[675]26*/
27
[1110]28#include "yat/utility/Container2DIterator.h"
[1134]29#include "yat/utility/Index.h"
[1080]30#include "yat/utility/iterator_traits.h"
[1528]31#include "yat/utility/Matrix.h"
[1169]32#include "yat/utility/SmartPtr.h"
[675]33
[1528]34#include <boost/iterator/permutation_iterator.hpp>
35
[757]36#include <iostream>
37#include <vector>
[455]38
39namespace theplu {
[680]40namespace yat {
[455]41namespace classifier { 
42
43  ///
[1192]44  /// @brief General view into utility::Matrix
[767]45  ///
[590]46  /// MatrixLookups can be used to create lookups/views into matrices
47  /// in a more general way than the views supported in the matrix
48  /// class. The object does not contain any data, but only a pointer
[1191]49  /// to a utility::Matrix and row and columns incices defining which
[590]50  /// sub-matrix to look into.  Each row and each column corresponds
[1191]51  /// to a row and a column in the utility::Matrix, respectively. This design
[590]52  /// allow for fast creation of sub-matrices, which is a common
[826]53  /// operation in most traning/validation procedures. The views are
54  /// const views in the sense that they cannot modify underlying
[1191]55  /// utility::Matrix.
[455]56  ///
[1191]57  /// A MatrixLookup can be created directly from a utility::Matrix or from
58  /// another MatrixLookup. In the latter case, the resulting
59  /// MatrixLookup is looking directly into the underlying utility::Matrix to
[590]60  /// avoid multiple lookups.
61  ///
62  /// There is a possibility to set the MatrixLookup as owner of the
[1191]63  /// underlying utility::Matrix. This implies that underlying data is deleted
[826]64  /// in destructor of MatrixLookup, but only if there is no other
65  /// owner of the underlying data. A reference counter is used to
66  /// keep track of number of owners. Ownership is copied in copy
67  /// constructors and assignments.
[590]68  ///
[1192]69  /// \see MatrixLookupWeighted
70  ///
[1170]71  class MatrixLookup
[455]72  {
[1063]73  public:
74    /// 'Read Only' iterator
[1530]75    typedef utility::Container2DIterator<const MatrixLookup, double, 
[1528]76                                         void, const double>
[1063]77    const_iterator;
[1062]78
[1125]79    /**
80       'Read only' iterator used to iterate over a column
81     */
[1528]82    typedef boost::permutation_iterator<utility::Matrix::const_column_iterator,
83                                        utility::Index::const_iterator> 
84    const_column_iterator;
[1125]85
86    /**
87       'Read only' iterator used to iterate over a row
88     */
[1528]89    typedef const_column_iterator const_row_iterator;
[1104]90
[455]91    ///
[590]92    /// Constructor creating a lookup into the entire @a matrix.
[966]93    /// \param matrix underlying matrix
[658]94    /// @param own if true MatrixLookup owns its underlying @a matrix
[455]95    ///
[826]96    /// @note If \a own is true and \a matrix is already owned by some
97    /// other object, this will lead to \a matrix having multiple
98    /// owners without the owners being aware of each
99    /// other. Consequently multiple deletion will occur.
100    ///
[536]101    /// @note If @a matrix goes out of scope or is deleted, the
102    /// MatrixLookup becomes invalid and the result of further use is
103    /// undefined.
104    ///
[1121]105    MatrixLookup(const utility::Matrix& matrix, const bool own=false);
[455]106
[590]107    ///
108    /// Constructor creating a lookup into a sub-matrix of @a matrix.
109    /// The @a row and @a column define what sub-matrix to look into,
110    /// in other words, the created MatrixLookup will fullfill the
111    /// following: \f$ MatrixLookup(i,j)=matrix(row[i],column[j])
112    /// \f$. This also means that number of rows in created
113    /// MatrixLookup is equal to size of vector @a row, and number of
114    /// columns is equal to size of vector @a column.
115    ///
[536]116    /// @note If @a matrix goes out of scope or is deleted, the
117    /// MatrixLookup becomes invalid and the result of further use is
118    /// undefined.
119    ///
[1134]120    MatrixLookup(const utility::Matrix& matrix, const utility::Index& row, 
121                 const utility::Index& column);
[455]122
[533]123    ///
[648]124    /// Constructor creating a lookup into a sub-matrix of @a matrix.
[590]125    ///
[656]126    /// If @a row_vectors is true the new MatrixLookup will consist
[590]127    /// of the row vectors defined by @a index. This means that the
128    /// created MatrixLookup will fullfill:
129    /// \f$ MatrixLookup(i,j)=matrix(i,index[j]) \f$
130    ///
131    /// If @a row_vectors is false the new MatrixLookup will be consist
132    /// of the rolumn vectors defined by @a index. This means that the
133    /// created MatrixLookup will fullfill:
134    /// \f$ MatrixLookup(i,j)=matrix(index[i],j) \f$
135    ///
[536]136    /// @note If @a matrix goes out of scope or is deleted, the
137    /// MatrixLookup becomes invalid and the result of further use is
138    /// undefined.
139    ///
[1121]140    MatrixLookup(const utility::Matrix& matrix, 
[1134]141                 const utility::Index& index, 
[565]142                 const bool row_vectors);
[455]143
[590]144    ///
145    /// @brief Copy constructor.
146    ///
[826]147    /// If \a other is owner of underlying data, constructed
148    /// MatrixLookup will also be set as owner of underlying data.
149    ///
[536]150    /// @note If underlying matrix goes out of scope or is deleted, the
151    /// MatrixLookup becomes invalid and the result of further use is
152    /// undefined.
153    ///
[826]154    MatrixLookup(const MatrixLookup& other);
[455]155
[590]156    ///
[826]157    /// @brief Create a sub-MatrixLookup.
158    ///
159    /// The Lookup is independent of
[590]160    /// MatrixLookup @a ml. The MatrixLookup is created to look
161    /// directly into the underlying matrix to avoid multiple lookups.
162    ///
[826]163    /// If \a ml is owner of underlying data, constructed
164    /// MatrixLookup will also be set as owner of underlying data.
165    ///
[590]166    /// The @a row and @a column define what sub-matrix to look into,
167    /// in other words, the created MatrixLookup will fullfill the
[826]168    /// following: MatrixLookup(i,j)=ml(row[i],column[j]). This
[590]169    /// also means that number of rows in created MatrixLookup is
170    /// equal to size of vector @a row, and number of columns is equal
171    /// to size of vector @a column.
172    ///
[826]173    /// If \a ml is owner of underlying data, constructed
174    /// MatrixLookup will also be set as owner of underlying data.
175    ///
[536]176    /// @note If underlying matrix goes out of scope or is deleted, the
177    /// MatrixLookup becomes invalid and the result of further use is
178    /// undefined.
179    ///
[1134]180    MatrixLookup(const MatrixLookup& ml, const utility::Index& row, 
181                 const utility::Index& column);
[469]182
[590]183    ///
184    /// Constructor creating a lookup into a sub-matrix of
185    /// @a ml. The MatrixLookup is created to look directly into the
186    /// underlying matrix to avoid multiple lookups.
187    ///
[656]188    /// If @a row_vectors is true the new MatrixLookup will consist
[590]189    /// of the row vectors defined by @a index. This means that the
190    /// created MatrixLookup will fullfill:
[826]191    /// MatrixLookup(i,j)=ml(i,index[j])
[590]192    ///
[656]193    /// If @a row_vectors is false the new MatrixLookup will consist
[590]194    /// of the rolumn vectors defined by @a index. This means that the
195    /// created MatrixLookup will fullfill:
196    /// \f$ MatrixLookup(i,j) = ml(index[i],j) \f$
197    ///
[826]198    /// If \a ml is owner of underlying data, constructed
199    /// MatrixLookup will also be set as owner of underlying data.
200    ///
[536]201    /// @note If underlying matrix goes out of scope or is deleted, the
202    /// MatrixLookup becomes invalid and the result of further use is
203    /// undefined.
204    ///
[1134]205    MatrixLookup(const MatrixLookup& ml, const utility::Index&, 
[565]206                 const bool row_vectors);
[469]207
[455]208    ///
[537]209    /// Constructor creating a MatrixLookup with @a rows rows, @a
210    /// columns columns, and all values are set to @a value. Created
[590]211    /// MatrixLookup owns its underlying matrix.
[537]212    ///
213    MatrixLookup(const size_t rows, const size_t columns, const double value=0);
214
215    ///
[590]216    /// @brief The istream constructor.
[455]217    ///
[590]218    /// In construction the underlying matrix is created from
219    /// stream. The MatrixLookup will be owner of the underlying
220    /// matrix.
221    ///
222    /// @see matrix(istream&) for details.
223    ///
224    MatrixLookup(std::istream&, char sep='\0');
225
226    ///
[826]227    /// @brief Destructor.
[590]228    ///
[826]229    /// If ownership is set true and there is no other owner of
230    /// underlying data, underlying data is deleted.
231    ///
[537]232    virtual ~MatrixLookup();
[455]233
[656]234    /**
[1066]235       Iterator iterates along a row. When end of row is reached it
236       jumps to beginning of next row.
237
238       \return const_iterator pointing to upper-left element.
[1062]239     */
240    const_iterator begin(void) const;
[1063]241
242    /**
[1066]243       Iterator iterates along a column.
244
245       \return iterator pointing to first element of column \a i.
[1063]246     */
[1104]247    const_column_iterator begin_column(size_t) const;
[1062]248
249    /**
[1066]250       Iterator iterates along a column.
251
252       \return const_iterator pointing to first element of column \a i.
[1063]253     */
[1104]254    const_row_iterator begin_row(size_t) const;
[1063]255
256    /**
[1170]257       \return number of columns
258    */
259    size_t columns(void) const;
260
261    /**
[1066]262       \return const_iterator pointing to end of matrix
[1063]263     */
264    const_iterator end(void) const;
265
266    /**
[1066]267       \return const_iterator pointing to end of column \a i
[1063]268     */
[1104]269    const_column_iterator end_column(size_t) const;
[1063]270
271    /**
[1066]272       \return const_iterator pointing to end of row \a i
[1063]273     */
[1104]274    const_row_iterator end_row(size_t) const;
[1063]275
[1170]276    /**
277       \return number of rows
278    */
279    size_t rows(void) const;
280
[604]281    ///
[631]282    /// @return false
283    ///
284    bool weighted(void) const;
285
286    ///
[482]287    /// Access operator
288    ///
289    /// @return element
290    ///
[720]291    double operator()(const size_t row, const size_t column) const;
[455]292
[556]293    ///
294    /// @brief assigment operator
295    ///
[590]296    /// Does only change MatrixLookup not the underlying matrix
[826]297    /// object. However if the MatrixLookup is owner (and the only owner)
298    /// of its underlying
[590]299    /// matrix, that matrix will be deleted here.
300    ///
[556]301    const MatrixLookup& operator=(const MatrixLookup&);
302   
[455]303  private:
[1035]304    friend class MatrixLookupWeighted;
305
[1170]306    utility::Index column_index_;
[1169]307    typedef utility::SmartPtr<const utility::Matrix> MatrixP;
308    MatrixP data_;
[1170]309    utility::Index row_index_;
310
311    // for assertions
312    bool validate(void) const;
[455]313  }; 
314 
[1169]315  ///
[1170]316  /// The output operator MatrixLookup
[1169]317  ///
318  std::ostream& operator<< (std::ostream& s, const MatrixLookup&);
319
[680]320}}} // of namespace classifier, yat, and theplu
[455]321
322#endif
Note: See TracBrowser for help on using the repository browser.