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

Last change on this file since 720 was 720, checked in by Jari Häkkinen, 15 years ago

Fixes #170. Almost all inlines removed, some classes have no cc file.

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