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

Last change on this file since 826 was 826, checked in by Peter, 15 years ago

documentation and some minor fixes Fixes #135

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