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

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

refs #247, #252, and #267

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