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

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

finishing cleaning

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date ID
File size: 8.2 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 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 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 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.
159    ///
160    virtual ~MatrixLookup();
161
162    /**
163       the new MatrixLookup will consist of the rolumn vectors
164       defined by @a index. This means that the returned MatrixLookup
165       will fullfill: \f$ returned(i,j) = original(index[i],j) \f$
166
167       @note If underlying matrix goes out of scope or is deleted, the
168       returned pointer becomes invalid and the result of further use is
169       undefined.
170   
171    */
172    const MatrixLookup* selected(const std::vector<size_t>&) const;
173
174    ///
175    /// The created MatrixLookup corresponds to all rows and the
176    /// columns defined by @a index in the original MatrixLookup. The
177    /// created MatrixLookup will fullfill:
178    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
179    ///
180    /// @return pointer to sub-Lookup of the MatrixLookup
181    ///
182    /// @note If underlying matrix goes out of scope or is deleted, the
183    /// returned pointer becomes invalid and the result of further use is
184    /// undefined.
185    ///
186    /// @Note Returns a dynamically allocated DataLookup2D, which has
187    /// to be deleted by the caller to avoid memory leaks.
188    ///
189    const MatrixLookup* training_data(const std::vector<size_t>& index) const;
190   
191    ///
192    /// The created MatrixLookup corresponds to all rows and the
193    /// columns defined by @a index in the original MatrixLookup. The
194    /// created MatrixLookup will fullfill:
195    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
196    ///
197    /// @return pointer to sub-Lookup of the MatrixLookup
198    ///
199    /// @note If underlying matrix goes out of scope or is deleted, the
200    /// returned pointer becomes invalid and the result of further use is
201    /// undefined.
202    ///
203    const MatrixLookup* validation_data(const std::vector<size_t>&,
204                                        const std::vector<size_t>&) const;
205    ///
206    /// @return false
207    ///
208    bool weighted(void) const;
209
210    ///
211    /// Access operator
212    ///
213    /// @return element
214    ///
215    inline double operator()(const size_t row, const size_t column) const
216    { 
217      assert(row<rows());
218      assert(column<columns());
219      return (*data_)(row_index_[row], column_index_[column]); 
220    }
221
222    ///
223    /// @brief assigment operator
224    ///
225    /// Does only change MatrixLookup not the underlying matrix
226    /// object. However if the MatrixLookup is owner of its underlying
227    /// matrix, that matrix will be deleted here.
228    ///
229    const MatrixLookup& operator=(const MatrixLookup&);
230   
231  private:
232    const utility::matrix* data_;
233  }; 
234 
235  ///
236  /// The output operator MatrixLookup
237  ///
238  std::ostream& operator<< (std::ostream& s, const MatrixLookup&);
239
240}} // of namespace classifier and namespace theplu
241
242#endif
Note: See TracBrowser for help on using the repository browser.