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

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

working on #247

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date ID
File size: 11.2 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    ///
81    /// Constructor creating a lookup into the entire @a matrix.
82    /// \param matrix underlying matrix
83    /// @param own if true MatrixLookup owns its underlying @a matrix
84    ///
85    /// @note If \a own is true and \a matrix is already owned by some
86    /// other object, this will lead to \a matrix having multiple
87    /// owners without the owners being aware of each
88    /// other. Consequently multiple deletion will occur.
89    ///
90    /// @note If @a matrix goes out of scope or is deleted, the
91    /// MatrixLookup becomes invalid and the result of further use is
92    /// undefined.
93    ///
94    MatrixLookup(const utility::matrix& matrix, const bool own=false);
95
96    ///
97    /// Constructor creating a lookup into a sub-matrix of @a matrix.
98    /// The @a row and @a column define what sub-matrix to look into,
99    /// in other words, the created MatrixLookup will fullfill the
100    /// following: \f$ MatrixLookup(i,j)=matrix(row[i],column[j])
101    /// \f$. This also means that number of rows in created
102    /// MatrixLookup is equal to size of vector @a row, and number of
103    /// columns is equal to size of vector @a column.
104    ///
105    /// @note If @a matrix goes out of scope or is deleted, the
106    /// MatrixLookup becomes invalid and the result of further use is
107    /// undefined.
108    ///
109    MatrixLookup(const utility::matrix& matrix, const std::vector<size_t>& row, 
110                 const std::vector<size_t>& column);
111
112    ///
113    /// Constructor creating a lookup into a sub-matrix of @a matrix.
114    ///
115    /// If @a row_vectors is true the new MatrixLookup will consist
116    /// of the row vectors defined by @a index. This means that the
117    /// created MatrixLookup will fullfill:
118    /// \f$ MatrixLookup(i,j)=matrix(i,index[j]) \f$
119    ///
120    /// If @a row_vectors is false the new MatrixLookup will be consist
121    /// of the rolumn vectors defined by @a index. This means that the
122    /// created MatrixLookup will fullfill:
123    /// \f$ MatrixLookup(i,j)=matrix(index[i],j) \f$
124    ///
125    /// @note If @a matrix goes out of scope or is deleted, the
126    /// MatrixLookup becomes invalid and the result of further use is
127    /// undefined.
128    ///
129    MatrixLookup(const utility::matrix& matrix, 
130                 const std::vector<size_t>& index, 
131                 const bool row_vectors);
132
133    ///
134    /// @brief Copy constructor.
135    ///
136    /// If \a other is owner of underlying data, constructed
137    /// MatrixLookup will also be set as owner of underlying data.
138    ///
139    /// @note If underlying matrix goes out of scope or is deleted, the
140    /// MatrixLookup becomes invalid and the result of further use is
141    /// undefined.
142    ///
143    MatrixLookup(const MatrixLookup& other);
144
145    ///
146    /// @brief Create a sub-MatrixLookup.
147    ///
148    /// The Lookup is independent of
149    /// MatrixLookup @a ml. The MatrixLookup is created to look
150    /// directly into the underlying matrix to avoid multiple lookups.
151    ///
152    /// If \a ml is owner of underlying data, constructed
153    /// MatrixLookup will also be set as owner of underlying data.
154    ///
155    /// The @a row and @a column define what sub-matrix to look into,
156    /// in other words, the created MatrixLookup will fullfill the
157    /// following: MatrixLookup(i,j)=ml(row[i],column[j]). This
158    /// also means that number of rows in created MatrixLookup is
159    /// equal to size of vector @a row, and number of columns is equal
160    /// to size of vector @a column.
161    ///
162    /// If \a ml is owner of underlying data, constructed
163    /// MatrixLookup will also be set as owner of underlying data.
164    ///
165    /// @note If underlying matrix goes out of scope or is deleted, the
166    /// MatrixLookup becomes invalid and the result of further use is
167    /// undefined.
168    ///
169    MatrixLookup(const MatrixLookup& ml, const std::vector<size_t>& row, 
170                 const std::vector<size_t>& column);
171
172    ///
173    /// Constructor creating a lookup into a sub-matrix of
174    /// @a ml. The MatrixLookup is created to look directly into the
175    /// underlying matrix to avoid multiple lookups.
176    ///
177    /// If @a row_vectors is true the new MatrixLookup will consist
178    /// of the row vectors defined by @a index. This means that the
179    /// created MatrixLookup will fullfill:
180    /// MatrixLookup(i,j)=ml(i,index[j])
181    ///
182    /// If @a row_vectors is false the new MatrixLookup will consist
183    /// of the rolumn vectors defined by @a index. This means that the
184    /// created MatrixLookup will fullfill:
185    /// \f$ MatrixLookup(i,j) = ml(index[i],j) \f$
186    ///
187    /// If \a ml is owner of underlying data, constructed
188    /// MatrixLookup will also be set as owner of underlying data.
189    ///
190    /// @note If underlying matrix goes out of scope or is deleted, the
191    /// MatrixLookup becomes invalid and the result of further use is
192    /// undefined.
193    ///
194    MatrixLookup(const MatrixLookup& ml, const std::vector<size_t>&, 
195                 const bool row_vectors);
196
197    ///
198    /// Constructor creating a MatrixLookup with @a rows rows, @a
199    /// columns columns, and all values are set to @a value. Created
200    /// MatrixLookup owns its underlying matrix.
201    ///
202    MatrixLookup(const size_t rows, const size_t columns, const double value=0);
203
204    ///
205    /// @brief The istream constructor.
206    ///
207    /// In construction the underlying matrix is created from
208    /// stream. The MatrixLookup will be owner of the underlying
209    /// matrix.
210    ///
211    /// @see matrix(istream&) for details.
212    ///
213    MatrixLookup(std::istream&, char sep='\0');
214
215    ///
216    /// @brief Destructor.
217    ///
218    /// If ownership is set true and there is no other owner of
219    /// underlying data, underlying data is deleted.
220    ///
221    virtual ~MatrixLookup();
222
223    /**
224       Iterator iterates along a row. When end of row is reached it
225       jumps to beginning of next row.
226
227       \return const_iterator pointing to upper-left element.
228     */
229    const_iterator begin(void) const;
230
231    /**
232       Iterator iterates along a column.
233
234       \return iterator pointing to first element of column \a i.
235     */
236    const_iterator begin_column(size_t) const;
237
238    /**
239       Iterator iterates along a column.
240
241       \return const_iterator pointing to first element of column \a i.
242     */
243    const_iterator begin_row(size_t) const;
244
245    /**
246       \return const_iterator pointing to end of matrix
247     */
248    const_iterator end(void) const;
249
250    /**
251       \return const_iterator pointing to end of column \a i
252     */
253    const_iterator end_column(size_t) const;
254
255    /**
256       \return const_iterator pointing to end of row \a i
257     */
258    const_iterator end_row(size_t) const;
259
260    /**
261       the new MatrixLookup will consist of the rolumn vectors
262       defined by @a index. This means that the returned MatrixLookup
263       will fullfill: \f$ returned(i,j) = original(index[i],j) \f$
264
265       @note If underlying matrix goes out of scope or is deleted, the
266       returned pointer becomes invalid and the result of further use is
267       undefined.
268   
269    */
270    const MatrixLookup* selected(const std::vector<size_t>&) const;
271
272    ///
273    /// The created MatrixLookup corresponds to all rows and the
274    /// columns defined by @a index in the original MatrixLookup. The
275    /// created MatrixLookup will fullfill:
276    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
277    ///
278    /// @return pointer to sub-Lookup of the MatrixLookup
279    ///
280    /// @note If underlying matrix goes out of scope or is deleted, the
281    /// returned pointer becomes invalid and the result of further use is
282    /// undefined.
283    ///
284    /// @Note Returns a dynamically allocated DataLookup2D, which has
285    /// to be deleted by the caller to avoid memory leaks.
286    ///
287    const MatrixLookup* training_data(const std::vector<size_t>& index) const;
288   
289    ///
290    /// The created MatrixLookup corresponds to all rows and the
291    /// columns defined by @a index in the original MatrixLookup. The
292    /// created MatrixLookup will fullfill:
293    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
294    ///
295    /// @return pointer to sub-Lookup of the MatrixLookup
296    ///
297    /// @note If underlying matrix goes out of scope or is deleted, the
298    /// returned pointer becomes invalid and the result of further use is
299    /// undefined.
300    ///
301    const MatrixLookup* validation_data(const std::vector<size_t>&,
302                                        const std::vector<size_t>&) const;
303    ///
304    /// @return false
305    ///
306    bool weighted(void) const;
307
308    ///
309    /// Access operator
310    ///
311    /// @return element
312    ///
313    double operator()(const size_t row, const size_t column) const;
314
315    ///
316    /// @brief assigment operator
317    ///
318    /// Does only change MatrixLookup not the underlying matrix
319    /// object. However if the MatrixLookup is owner (and the only owner)
320    /// of its underlying
321    /// matrix, that matrix will be deleted here.
322    ///
323    const MatrixLookup& operator=(const MatrixLookup&);
324   
325  private:
326    friend class MatrixLookupWeighted;
327
328    const utility::matrix* data_;
329  }; 
330 
331}}} // of namespace classifier, yat, and theplu
332
333#endif
Note: See TracBrowser for help on using the repository browser.