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

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

Iterators for MatrixLookup?

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