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

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

ref #96 included FeatureSelection? in CrossSplitter?. Also happened to add properties to files

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 9.0 KB
Line 
1// $Id: MatrixLookup.h 607 2006-08-29 14:42:28Z peter $
2
3#ifndef _theplu_classifier_matrix_lookup_
4#define _theplu_classifier_matrix_lookup_
5
6#include <c++_tools/classifier/DataLookup2D.h>
7#include <c++_tools/gslapi/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 gslapi::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 gslapi::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 @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 gslapi::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    /// Access operator
228    ///
229    /// @return element
230    ///
231    inline double operator()(const size_t row, const size_t column) const
232    { 
233      assert(row<rows());
234      assert(column<columns());
235      return (*data_)(row_index_[row], column_index_[column]); 
236    }
237
238    ///
239    /// @brief assigment operator
240    ///
241    /// Does only change MatrixLookup not the underlying matrix
242    /// object. However if the MatrixLookup is owner of its underlying
243    /// matrix, that matrix will be deleted here.
244    ///
245    const MatrixLookup& operator=(const MatrixLookup&);
246   
247  private:
248    const gslapi::matrix* data_;
249  }; 
250 
251  ///
252  /// The output operator MatrixLookup
253  ///
254  std::ostream& operator<< (std::ostream& s, const MatrixLookup&);
255
256}} // of namespace classifier and namespace theplu
257
258#endif
Note: See TracBrowser for help on using the repository browser.