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

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

adding iterator typedefs in MatrixLookup?

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