source: trunk/c++_tools/classifier/MatrixLookupWeighted.h @ 597

Last change on this file since 597 was 597, checked in by Markus Ringnér, 15 years ago

Fixed comments so they pass without some of the complaits from doxygen. Have not looked at the actual contents of comments

File size: 8.6 KB
Line 
1// $Id$
2
3#ifndef _theplu_classifier_matrix_lookup_weighted_
4#define _theplu_classifier_matrix_lookup_weighted_
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  /// A MatrixLookupWeighted is very similar to a MatrixLookup, but
17  /// contains a pointer to a weight matrix as well meaning each data
18  /// element is associated to weight.
19  ///
20  /// A MatrixLookupWeighted can be created directly from a matrix or
21  /// from an other MatrixLookupWeighted. In the latter case, the
22  /// resulting MatrixLookupWeighted is looking directly into the
23  /// underlying matrix to avoid multiple lookups.
24  ///
25  /// There is a possibility to set the MatrixLookupWeighted as owner
26  /// of the underlying matrices (data and weight). In that case the
27  /// underlying matrix will be destroyed in the
28  /// destructor. Consequently, the underlying matricis must have been
29  /// dynamically allocated and no other MatrixLookupWeighted can own
30  /// the matrices.
31  ///
32  /// @todo add on weight part
33  ///
34  class MatrixLookupWeighted : public DataLookup2D
35  {
36 
37  public:
38
39
40    ///
41    /// Constructor creating a lookup into the entire @a matrix.
42    ///
43    /// @note If @a matrix or @a weights goes out of scope or is
44    /// deleted, the MatrixLookupWeighted becomes invalid and the
45    /// result of further use is undefined.
46    ///
47    MatrixLookupWeighted(const gslapi::matrix& matrix, 
48                         const gslapi::matrix& weights);
49
50    ///
51    /// Constructor creating a lookup into a sub-matrix of @a matrix.
52    /// The @a row and @a column define what sub-matrix to look into,
53    /// in other words, the created MatrixLookupWeighted will fullfill
54    /// the following: \f$
55    /// MatrixLookupWeighted(i,j)=matrix(row[i],column[j])
56    /// weights(row[i],column[j])\f$. This also means that number of
57    /// rows in created MatrixLookupWeighted is equal to size of
58    /// vector @a row, and number of columns is equal to size of
59    /// vector @a column.
60    ///
61    /// @note If @a matrix or @a weights goes out of scope or is deleted, the
62    /// MatrixLookupWeighted becomes invalid and the result of further use is
63    /// undefined.
64    ///
65    MatrixLookupWeighted(const gslapi::matrix& matrix, 
66                         const gslapi::matrix& weights, 
67                         const std::vector<size_t>& row, 
68                         const std::vector<size_t>& column);
69
70    ///
71    /// Constructor creating a lookup into a sub-matrix of @matrix.
72    ///
73    /// If @a row_vectors is true the new MatrixLookupWeighted will be
74    /// consist of the row vectors defined by @a index. This means
75    /// that the created MatrixLookupWeighted will fullfill: \f$
76    /// MatrixLookupWeighted(i,j)=matrix(i,index[j])*weights(i,index[j])
77    /// \f$
78    ///
79    /// If @a row_vectors is false the new MatrixLookupWeighted will be consist
80    /// of the rolumn vectors defined by @a index. This means that the
81    /// created MatrixLookupWeighted will fullfill:
82    /// \f$ MatrixLookupWeighted(i,j)=matrix(index[i],j) \f$
83    ///
84    /// @note If @a matrix or @a weights goes out of scope or is
85    /// deleted, the MatrixLookupWeighted becomes invalid and the
86    /// result of further use is undefined.
87    ///
88    MatrixLookupWeighted(const gslapi::matrix& matrix, 
89                         const gslapi::matrix& weights, 
90                         const std::vector<size_t>& index, 
91                         const bool row_vectors);
92
93    ///
94    /// @brief
95    ///
96    /// @note If underlying matrix goes out of scope or is deleted, the
97    /// MatrixLookupWeighted becomes invalid and the result of further use is
98    /// undefined.
99    ///
100    //MatrixLookupWeighted(const MatrixLookup&, const MatrixLookup);
101
102    ///
103    /// @brief Copy constructor.
104    ///
105    /// @note If underlying matrix goes out of scope or is deleted, the
106    /// MatrixLookupWeighted becomes invalid and the result of further use is
107    /// undefined.
108    ///
109    MatrixLookupWeighted(const MatrixLookupWeighted&);
110
111    ///
112    /// Creates a sub-MatrixLookupWeighted. The Lookup is independent of
113    /// MatrixLookupWeighted @a ml. The MatrixLookupWeighted is created to look
114    /// directly into the underlying matrix to avoid multiple lookups.
115    ///
116    /// The @a row and @a column define what sub-matrix to look into,
117    /// in other words, the created MatrixLookupWeighted will fullfill the
118    /// following: \f$ MatrixLookupWeighted(i,j)=ml(row[i],column[j]) \f$. This
119    /// also means that number of rows in created MatrixLookupWeighted is
120    /// equal to size of vector @a row, and number of columns is equal
121    /// to size of vector @a column.
122    ///
123    /// @note If underlying matrix goes out of scope or is deleted, the
124    /// MatrixLookupWeighted becomes invalid and the result of further use is
125    /// undefined.
126    ///
127    MatrixLookupWeighted(const MatrixLookupWeighted& ml, 
128                         const std::vector<size_t>& row, 
129                         const std::vector<size_t>& column);
130
131    ///
132    /// Constructor creating a lookup into a sub-matrix of
133    /// @a ml. The MatrixLookupWeighted is created to look directly into the
134    /// underlying matrix to avoid multiple lookups.
135    ///
136    /// If @a row_vectors is true the new MatrixLookupWeighted will be consist
137    /// of the row vectors defined by @a index. This means that the
138    /// created MatrixLookupWeighted will fullfill:
139    /// \f$ MatrixLookupWeighted(i,j)=ml(i,index[j])\f$
140    ///
141    /// If @a row_vectors is false the new MatrixLookupWeighted will be consist
142    /// of the rolumn vectors defined by @a index. This means that the
143    /// created MatrixLookupWeighted will fullfill:
144    /// \f$ MatrixLookupWeighted(i,j) = ml(index[i],j) \f$
145    ///
146    /// @note If underlying matrix goes out of scope or is deleted, the
147    /// MatrixLookupWeighted becomes invalid and the result of further use is
148    /// undefined.
149    ///
150    MatrixLookupWeighted(const MatrixLookupWeighted& ml, 
151                         const std::vector<size_t>&, 
152                         const bool row_vectors);
153
154    ///
155    /// Constructor creating a MatrixLookupWeighted with @a rows rows, @a
156    /// columns columns, and all values are set to @a value. Created
157    /// MatrixLookupWeighted owns its underlying matrix.
158    ///
159    MatrixLookupWeighted(const size_t rows, const size_t columns, 
160                         const double value=0);
161
162    ///
163    /// @brief The istream constructor.
164    ///
165    /// In construction the underlying matrix is created from
166    /// stream. The MatrixLookupWeighted will be owner of the underlying
167    /// matrix.
168    ///
169    /// @see matrix(istream&) for details.
170    ///
171    MatrixLookupWeighted(std::istream&, char sep='\0');
172
173    ///
174    /// Destructor. If MatrixLookup is owner of underlying matrix, the
175    /// matrix is destroyed.
176    ///
177    virtual ~MatrixLookupWeighted();
178
179   
180    ///
181    /// The created MatrixLookupWeighted corresponds to all rows and the
182    /// columns defined by @a index in the original MatrixLookupWeighted. The
183    /// created MatrixLookupWeighted will fullfill:
184    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
185    ///
186    /// @return pointer to sub-Lookup of the MatrixLookupWeighted
187    ///
188    /// @note If underlying matrix goes out of scope or is deleted, the
189    /// returned pointer becomes invalid and the result of further use is
190    /// undefined.
191    ///
192    const MatrixLookupWeighted* training_data(const std::vector<size_t>& index) const;
193   
194    ///
195    /// The created MatrixLookupWeighted corresponds to all rows and the
196    /// columns defined by @a index in the original MatrixLookupWeighted. The
197    /// created MatrixLookupWeighted will fullfill:
198    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
199    ///
200    /// @return pointer to sub-Lookup of the MatrixLookupWeighted
201    ///
202    /// @note If underlying matrix goes out of scope or is deleted, the
203    /// returned pointer becomes invalid and the result of further use is
204    /// undefined.
205    ///
206    const MatrixLookupWeighted* validation_data(const std::vector<size_t>&,
207                                        const std::vector<size_t>&) const;
208
209    ///
210    /// Access operator
211    ///
212    /// @return weight * data for element \f$ i j\f$
213    ///
214    inline double operator()(const size_t row, const size_t column) const
215    { 
216      assert(row<rows());
217      assert(column<columns());
218      return (*data_)(row_index_[row], column_index_[column])*
219        (*weights_)(row_index_[row], column_index_[column]); 
220    }
221
222    ///
223    /// @brief assigment operator
224    ///
225    /// Does only change MatrixLookupWeighted not the underlying matrix
226    /// object. However if the MatrixLookupWeighted is owner of its underlying
227    /// matrix, that matrix will be deleted here.
228    ///
229    const MatrixLookupWeighted& operator=(const MatrixLookupWeighted&);
230   
231  private:
232    const gslapi::matrix* data_;
233    const gslapi::matrix* weights_;
234  }; 
235 
236  ///
237  /// The output operator MatrixLookupWeighted
238  ///
239  std::ostream& operator<< (std::ostream& s, const MatrixLookupWeighted&);
240
241}} // of namespace classifier and namespace theplu
242
243#endif
Note: See TracBrowser for help on using the repository browser.