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

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

fixes #342

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