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

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

redesigning Iterator class to hold a 2D container rather than 1D as before. refs #267

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