source: branches/0.4-stable/yat/classifier/MatrixLookup.h @ 1392

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

trac has moved

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date ID
File size: 10.4 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 Peter Johansson, Markus Ringnér
8  Copyright (C) 2006 Jari Häkkinen, Peter Johansson, Markus Ringnér
9  Copyright (C) 2007 Jari Häkkinen, Peter Johansson
10  Copyright (C) 2008 Peter Johansson
11
12  This file is part of the yat library, http://dev.thep.lu.se/yat
13
14  The yat library is free software; you can redistribute it and/or
15  modify it under the terms of the GNU General Public License as
16  published by the Free Software Foundation; either version 2 of the
17  License, or (at your option) any later version.
18
19  The yat library is distributed in the hope that it will be useful,
20  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22  General Public License for more details.
23
24  You should have received a copy of the GNU General Public License
25  along with this program; if not, write to the Free Software
26  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
27  02111-1307, USA.
28*/
29
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 utility::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 utility::Matrix, 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  /// utility::Matrix.
61  ///
62  /// A MatrixLookup can be created directly from a utility::Matrix or from
63  /// another MatrixLookup. In the latter case, the resulting
64  /// MatrixLookup is looking directly into the underlying utility::Matrix to
65  /// avoid multiple lookups.
66  ///
67  /// There is a possibility to set the MatrixLookup as owner of the
68  /// underlying utility::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  /// \see MatrixLookupWeighted
75  ///
76  class MatrixLookup
77  {
78  public:
79    /// 'Read Only' iterator
80    typedef utility::StrideIterator<
81    utility::Container2DIterator<const MatrixLookup, const double, void, 
82                                 const double> >
83    const_iterator;
84
85    /**
86       'Read only' iterator used to iterate over a column
87     */
88    typedef const_iterator const_column_iterator;
89
90    /**
91       'Read only' iterator used to iterate over a row
92     */
93    typedef const_iterator const_row_iterator;
94
95    ///
96    /// Constructor creating a lookup into the entire @a matrix.
97    /// \param matrix underlying matrix
98    /// @param own if true MatrixLookup owns its underlying @a matrix
99    ///
100    /// @note If \a own is true and \a matrix is already owned by some
101    /// other object, this will lead to \a matrix having multiple
102    /// owners without the owners being aware of each
103    /// other. Consequently multiple deletion will occur.
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 bool own=false);
110
111    ///
112    /// Constructor creating a lookup into a sub-matrix of @a matrix.
113    /// The @a row and @a column define what sub-matrix to look into,
114    /// in other words, the created MatrixLookup will fullfill the
115    /// following: \f$ MatrixLookup(i,j)=matrix(row[i],column[j])
116    /// \f$. This also means that number of rows in created
117    /// MatrixLookup is equal to size of vector @a row, and number of
118    /// columns is equal to size of vector @a column.
119    ///
120    /// @note If @a matrix goes out of scope or is deleted, the
121    /// MatrixLookup becomes invalid and the result of further use is
122    /// undefined.
123    ///
124    MatrixLookup(const utility::Matrix& matrix, const utility::Index& row, 
125                 const utility::Index& column);
126
127    ///
128    /// Constructor creating a lookup into a sub-matrix of @a matrix.
129    ///
130    /// If @a row_vectors is true the new MatrixLookup will consist
131    /// of the row vectors defined by @a index. This means that the
132    /// created MatrixLookup will fullfill:
133    /// \f$ MatrixLookup(i,j)=matrix(i,index[j]) \f$
134    ///
135    /// If @a row_vectors is false the new MatrixLookup will be consist
136    /// of the rolumn vectors defined by @a index. This means that the
137    /// created MatrixLookup will fullfill:
138    /// \f$ MatrixLookup(i,j)=matrix(index[i],j) \f$
139    ///
140    /// @note If @a 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 utility::Matrix& matrix, 
145                 const utility::Index& index, 
146                 const bool row_vectors);
147
148    ///
149    /// @brief Copy constructor.
150    ///
151    /// If \a other is owner of underlying data, constructed
152    /// MatrixLookup will also be set as owner of underlying data.
153    ///
154    /// @note If underlying matrix goes out of scope or is deleted, the
155    /// MatrixLookup becomes invalid and the result of further use is
156    /// undefined.
157    ///
158    MatrixLookup(const MatrixLookup& other);
159
160    ///
161    /// @brief Create a sub-MatrixLookup.
162    ///
163    /// The Lookup is independent of
164    /// MatrixLookup @a ml. The MatrixLookup is created to look
165    /// directly into the underlying matrix to avoid multiple lookups.
166    ///
167    /// If \a ml is owner of underlying data, constructed
168    /// MatrixLookup will also be set as owner of underlying data.
169    ///
170    /// The @a row and @a column define what sub-matrix to look into,
171    /// in other words, the created MatrixLookup will fullfill the
172    /// following: MatrixLookup(i,j)=ml(row[i],column[j]). This
173    /// also means that number of rows in created MatrixLookup is
174    /// equal to size of vector @a row, and number of columns is equal
175    /// to size of vector @a column.
176    ///
177    /// If \a ml is owner of underlying data, constructed
178    /// MatrixLookup will also be set as owner of underlying data.
179    ///
180    /// @note If underlying matrix goes out of scope or is deleted, the
181    /// MatrixLookup becomes invalid and the result of further use is
182    /// undefined.
183    ///
184    MatrixLookup(const MatrixLookup& ml, const utility::Index& row, 
185                 const utility::Index& column);
186
187    ///
188    /// Constructor creating a lookup into a sub-matrix of
189    /// @a ml. The MatrixLookup is created to look directly into the
190    /// underlying matrix to avoid multiple lookups.
191    ///
192    /// If @a row_vectors is true the new MatrixLookup will consist
193    /// of the row vectors defined by @a index. This means that the
194    /// created MatrixLookup will fullfill:
195    /// MatrixLookup(i,j)=ml(i,index[j])
196    ///
197    /// If @a row_vectors is false the new MatrixLookup will consist
198    /// of the rolumn vectors defined by @a index. This means that the
199    /// created MatrixLookup will fullfill:
200    /// \f$ MatrixLookup(i,j) = ml(index[i],j) \f$
201    ///
202    /// If \a ml is owner of underlying data, constructed
203    /// MatrixLookup will also be set as owner of underlying data.
204    ///
205    /// @note If underlying matrix goes out of scope or is deleted, the
206    /// MatrixLookup becomes invalid and the result of further use is
207    /// undefined.
208    ///
209    MatrixLookup(const MatrixLookup& ml, const utility::Index&, 
210                 const bool row_vectors);
211
212    ///
213    /// Constructor creating a MatrixLookup with @a rows rows, @a
214    /// columns columns, and all values are set to @a value. Created
215    /// MatrixLookup owns its underlying matrix.
216    ///
217    MatrixLookup(const size_t rows, const size_t columns, const double value=0);
218
219    ///
220    /// @brief The istream constructor.
221    ///
222    /// In construction the underlying matrix is created from
223    /// stream. The MatrixLookup will be owner of the underlying
224    /// matrix.
225    ///
226    /// @see matrix(istream&) for details.
227    ///
228    MatrixLookup(std::istream&, char sep='\0');
229
230    ///
231    /// @brief Destructor.
232    ///
233    /// If ownership is set true and there is no other owner of
234    /// underlying data, underlying data is deleted.
235    ///
236    virtual ~MatrixLookup();
237
238    /**
239       Iterator iterates along a row. When end of row is reached it
240       jumps to beginning of next row.
241
242       \return const_iterator pointing to upper-left element.
243     */
244    const_iterator begin(void) const;
245
246    /**
247       Iterator iterates along a column.
248
249       \return iterator pointing to first element of column \a i.
250     */
251    const_column_iterator begin_column(size_t) const;
252
253    /**
254       Iterator iterates along a column.
255
256       \return const_iterator pointing to first element of column \a i.
257     */
258    const_row_iterator begin_row(size_t) const;
259
260    /**
261       \return number of columns
262    */
263    size_t columns(void) const;
264
265    /**
266       \return const_iterator pointing to end of matrix
267     */
268    const_iterator end(void) const;
269
270    /**
271       \return const_iterator pointing to end of column \a i
272     */
273    const_column_iterator end_column(size_t) const;
274
275    /**
276       \return const_iterator pointing to end of row \a i
277     */
278    const_row_iterator end_row(size_t) const;
279
280    /**
281       \return number of rows
282    */
283    size_t rows(void) const;
284
285    ///
286    /// @return false
287    ///
288    bool weighted(void) const;
289
290    ///
291    /// Access operator
292    ///
293    /// @return element
294    ///
295    double operator()(const size_t row, const size_t column) const;
296
297    ///
298    /// @brief assigment operator
299    ///
300    /// Does only change MatrixLookup not the underlying matrix
301    /// object. However if the MatrixLookup is owner (and the only owner)
302    /// of its underlying
303    /// matrix, that matrix will be deleted here.
304    ///
305    const MatrixLookup& operator=(const MatrixLookup&);
306   
307  private:
308    friend class MatrixLookupWeighted;
309
310    utility::Index column_index_;
311    typedef utility::SmartPtr<const utility::Matrix> MatrixP;
312    MatrixP data_;
313    utility::Index row_index_;
314
315    // for assertions
316    bool validate(void) const;
317  }; 
318 
319  ///
320  /// The output operator MatrixLookup
321  ///
322  std::ostream& operator<< (std::ostream& s, const MatrixLookup&);
323
324}}} // of namespace classifier, yat, and theplu
325
326#endif
Note: See TracBrowser for help on using the repository browser.