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

Last change on this file since 1169 was 1169, checked in by Peter, 14 years ago

refs #343 moving data to inherited classes and using SmartPtr?.

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