source: trunk/c++_tools/classifier/MatrixLookup.h @ 648

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

fixes #133 removed all errors reported from Doxygen. Only one error left which says Index is not documented but I don't want it to be documented actually we use the Doxygens preprocessor to skip documenting that class, yet Doxygen complains that class is not documented huh. Only solution would be to move that class to its own file and not keep it together with SVM.

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