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

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

some more docs

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