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

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

Refs #185.

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