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

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

fixing some doxygen warnings

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date ID
File size: 10.1 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/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 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       the new MatrixLookup will consist of the rolumn vectors
220       defined by @a index. This means that the returned MatrixLookup
221       will fullfill: \f$ returned(i,j) = original(index[i],j) \f$
222
223       @note If underlying matrix goes out of scope or is deleted, the
224       returned pointer becomes invalid and the result of further use is
225       undefined.
226   
227    */
228    const MatrixLookup* selected(const std::vector<size_t>&) const;
229
230    ///
231    /// The created MatrixLookup corresponds to all rows and the
232    /// columns defined by @a index in the original MatrixLookup. The
233    /// created MatrixLookup will fullfill:
234    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
235    ///
236    /// @return pointer to sub-Lookup of the MatrixLookup
237    ///
238    /// @note If underlying matrix goes out of scope or is deleted, the
239    /// returned pointer becomes invalid and the result of further use is
240    /// undefined.
241    ///
242    /// @Note Returns a dynamically allocated DataLookup2D, which has
243    /// to be deleted by the caller to avoid memory leaks.
244    ///
245    const MatrixLookup* training_data(const std::vector<size_t>& index) const;
246   
247    ///
248    /// The created MatrixLookup corresponds to all rows and the
249    /// columns defined by @a index in the original MatrixLookup. The
250    /// created MatrixLookup will fullfill:
251    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
252    ///
253    /// @return pointer to sub-Lookup of the MatrixLookup
254    ///
255    /// @note If underlying matrix goes out of scope or is deleted, the
256    /// returned pointer becomes invalid and the result of further use is
257    /// undefined.
258    ///
259    const MatrixLookup* validation_data(const std::vector<size_t>&,
260                                        const std::vector<size_t>&) const;
261    ///
262    /// @return false
263    ///
264    bool weighted(void) const;
265
266    ///
267    /// Access operator
268    ///
269    /// @return element
270    ///
271    double operator()(const size_t row, const size_t column) const;
272
273    ///
274    /// @brief assigment operator
275    ///
276    /// Does only change MatrixLookup not the underlying matrix
277    /// object. However if the MatrixLookup is owner (and the only owner)
278    /// of its underlying
279    /// matrix, that matrix will be deleted here.
280    ///
281    const MatrixLookup& operator=(const MatrixLookup&);
282   
283  private:
284    const utility::matrix* data_;
285  }; 
286 
287}}} // of namespace classifier, yat, and theplu
288
289#endif
Note: See TracBrowser for help on using the repository browser.