source: trunk/yat/classifier/MatrixLookupWeighted.h @ 826

Last change on this file since 826 was 826, checked in by Peter, 16 years ago

documentation and some minor fixes Fixes #135

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date ID
File size: 10.8 KB
Line 
1#ifndef _theplu_yat_classifier_matrix_lookup_weighted_
2#define _theplu_yat_classifier_matrix_lookup_weighted_
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
29#include <iostream>
30#include <vector>
31
32namespace theplu {
33namespace yat {
34
35namespace utility {
36  class matrix;
37}
38
39namespace classifier { 
40
41  ///
42  /// @brief Class viewing into data and weight matrix.
43  ///
44  /// A MatrixLookupWeighted is very similar to a MatrixLookup, but
45  /// contains a pointer to a weight matrix as well meaning each data
46  /// element is associated to a weight.
47  ///
48  /// A MatrixLookupWeighted can be created directly from a matrix or
49  /// from an other MatrixLookupWeighted. In the latter case, the
50  /// resulting MatrixLookupWeighted is looking directly into the
51  /// underlying matrix to avoid multiple lookups.
52  ///
53  /// There is a possibility to set the MatrixLookupWeighted as owner
54  /// of the underlying matrices (data and weight).
55  /// This implies that underlying data is deleted
56  /// in destructor of MatrixLookupWeighted, but only if there is no other
57  /// owner of the underlying data. A reference counter is used to
58  /// keep track of number of owners. Ownership is copied in copy
59  /// constructors and assignments.
60  ///
61  class MatrixLookupWeighted : public DataLookup2D
62  {
63 
64  public:
65
66
67    ///
68    /// Constructor creating a lookup into the entire \a matrix and \a
69    /// weights.
70    ///
71    /// @note If @a matrix or @a weights goes out of scope or is
72    /// deleted, the MatrixLookupWeighted becomes invalid and the
73    /// result of further use is undefined.
74    ///
75    MatrixLookupWeighted(const utility::matrix& matrix, 
76                         const utility::matrix& weights,
77                         const bool owner=false);
78
79   
80    ///
81    /// Constructor creating a lookup into the entire @a matrix.  A
82    /// weight matrix is constructed with weights 1 for values and 0
83    /// for nan's in @a matrix.
84    ///
85    /// \see  bool utility::nan(const matrix&, matrix&);
86    ///
87    /// @note If @a matrix goes out of scope or
88    /// is deleted, the MatrixLookupWeighted becomes invalid and the
89    /// result of further use is undefined.
90    ///
91    MatrixLookupWeighted(const utility::matrix& matrix);
92
93
94    ///
95    /// Constructor creating a lookup into a sub-matrix of @a matrix.
96    /// The @a row and @a column define what sub-matrix to look into,
97    /// in other words, the created MatrixLookupWeighted will fullfill
98    /// the following:
99    /// MatrixLookupWeighted(i,j)=matrix(row[i],column[j])
100    /// weights(row[i],column[j]). This also means that number of
101    /// rows in created MatrixLookupWeighted is equal to size of
102    /// vector @a row, and number of columns is equal to size of
103    /// vector @a column.
104    ///
105    /// @note If @a matrix or @a weights 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 utility::matrix& matrix, 
110                         const utility::matrix& weights, 
111                         const std::vector<size_t>& row, 
112                         const std::vector<size_t>& column);
113
114    ///
115    /// Constructor creating a lookup into a sub-matrix of @a matrix.
116    ///
117    /// If @a row_vectors is true the new MatrixLookupWeighted will be
118    /// consist of the row vectors defined by @a index. This means
119    /// that the created MatrixLookupWeighted will fullfill:
120    /// MatrixLookupWeighted(i,j)=matrix(i,index[j])*weights(i,index[j])
121    ///
122    ///
123    /// If @a row_vectors is false the new MatrixLookupWeighted will be consist
124    /// of the rolumn vectors defined by @a index. This means that the
125    /// created MatrixLookupWeighted will fullfill:
126    ///
127    ///
128    /// @note If @a matrix or @a weights goes out of scope or is
129    /// deleted, the MatrixLookupWeighted becomes invalid and the
130    /// result of further use is undefined.
131    ///
132    MatrixLookupWeighted(const utility::matrix& matrix, 
133                         const utility::matrix& weights, 
134                         const std::vector<size_t>& index, 
135                         const bool row_vectors);
136
137    ///
138    /// @brief Copy constructor.
139    ///
140    /// If \a other is owner of underlying data, constructed
141    /// MatrixLookup will also be set as owner of underlying data.
142    ///
143    /// @note If underlying matrix goes out of scope or is deleted, the
144    /// MatrixLookupWeighted becomes invalid and the result of further use is
145    /// undefined.
146    ///
147    MatrixLookupWeighted(const MatrixLookupWeighted& other);
148
149    ///
150    /// Creates a sub-MatrixLookupWeighted. The Lookup is independent of
151    /// MatrixLookupWeighted @a ml. The MatrixLookupWeighted is created to look
152    /// directly into the underlying matrix to avoid multiple lookups.
153    ///
154    /// The @a row and @a column define what sub-matrix to look into,
155    /// in other words, the created MatrixLookupWeighted will fullfill the
156    /// following: \f$ MatrixLookupWeighted(i,j)=ml(row[i],column[j]) \f$. This
157    /// also means that number of rows in created MatrixLookupWeighted is
158    /// equal to size of vector @a row, and number of columns is equal
159    /// to size of vector @a column.
160    ///
161    /// If \a ml is owner of underlying data, constructed
162    /// MatrixLookup will also be set as owner of underlying data.
163    ///
164    /// @note If underlying matrix goes out of scope or is deleted, the
165    /// MatrixLookupWeighted becomes invalid and the result of further use is
166    /// undefined.
167    ///
168    MatrixLookupWeighted(const MatrixLookupWeighted& ml, 
169                         const std::vector<size_t>& row, 
170                         const std::vector<size_t>& column);
171
172    ///
173    /// Constructor creating a lookup into a sub-matrix of
174    /// @a ml. The MatrixLookupWeighted is created to look directly into the
175    /// underlying matrix to avoid multiple lookups.
176    ///
177    /// If @a row_vectors is true the new MatrixLookupWeighted will consist
178    /// of the row vectors defined by @a index. This means that the
179    /// created MatrixLookupWeighted will fullfill:
180    /// \f$ MatrixLookupWeighted(i,j)=ml(i,index[j])\f$
181    ///
182    /// If @a row_vectors is false the new MatrixLookupWeighted will consist
183    /// of the rolumn vectors defined by @a index. This means that the
184    /// created MatrixLookupWeighted will fullfill:
185    /// \f$ MatrixLookupWeighted(i,j) = ml(index[i],j) \f$
186    ///
187    /// If \a ml is owner of underlying data, constructed
188    /// MatrixLookup will also be set as owner of underlying data.
189    ///
190    /// @note If underlying matrix goes out of scope or is deleted, the
191    /// MatrixLookupWeighted becomes invalid and the result of further use is
192    /// undefined.
193    ///
194    MatrixLookupWeighted(const MatrixLookupWeighted& ml, 
195                         const std::vector<size_t>&, 
196                         const bool row_vectors);
197
198    ///
199    /// Constructor creating a MatrixLookupWeighted with @a rows rows, @a
200    /// columns columns, and all values are set to @a value. Created
201    /// MatrixLookupWeighted owns its underlying matrix.
202    ///
203    MatrixLookupWeighted(const size_t rows, const size_t columns, 
204                         const double value=0, const double weight=1);
205
206    ///
207    /// @brief The istream constructor.
208    ///
209    /// In construction the underlying matrix is created from
210    /// stream. The MatrixLookupWeighted will be owner of the underlying
211    /// matrix.
212    ///
213    /// @see matrix(istream&) for details.
214    ///
215    MatrixLookupWeighted(std::istream&, char sep='\0');
216
217    ///
218    /// Destructor. If MatrixLookup is owner (and the only owner) of
219    /// underlying matrix, the matrices are destroyed.
220    ///
221    virtual ~MatrixLookupWeighted();
222
223    ///
224    /// @return data value of element (@a row, @a column)
225    ///
226    double data(size_t row, size_t column) const;
227
228    /**
229       the new MatrixLookup will consist of the rolumn vectors
230       defined by @a index. This means that the returned
231       MatrixLookupWeighted
232       will fullfill:
233       returned(i,j) = original(index[i],j)
234
235       @note If underlying matrix goes out of scope or is deleted, the
236       returned pointer becomes invalid and the result of further use is
237       undefined.
238   
239    */
240    const MatrixLookupWeighted* selected(const std::vector<size_t>& i) const;
241
242    ///
243    /// The created MatrixLookupWeighted corresponds to all rows and the
244    /// columns defined by @a index in the original MatrixLookupWeighted. The
245    /// created MatrixLookupWeighted will fullfill:
246    /// novel_ml(i,j)=original(i,index[j]).
247    ///
248    /// @return pointer to sub-Lookup of the MatrixLookupWeighted
249    ///
250    /// @note If underlying matrix goes out of scope or is deleted, the
251    /// returned pointer becomes invalid and the result of further use is
252    /// undefined.
253    ///
254    const MatrixLookupWeighted* 
255    training_data(const std::vector<size_t>& index) const;
256   
257    ///
258    /// The created MatrixLookupWeighted corresponds to all rows and the
259    /// columns defined by @a index in the original MatrixLookupWeighted. The
260    /// created MatrixLookupWeighted will fullfill:
261    /// novel_ml(i,j)=original(i,index[j])
262    ///
263    /// @return pointer to sub-Lookup of the MatrixLookupWeighted
264    ///
265    /// @note If underlying matrix goes out of scope or is deleted, the
266    /// returned pointer becomes invalid and the result of further use is
267    /// undefined.
268    ///
269    const MatrixLookupWeighted* validation_data(const std::vector<size_t>&,
270                                        const std::vector<size_t>&) const;
271
272    ///
273    /// @return weight value of element (@a row, @a column)
274    ///
275    double weight(size_t row, size_t column) const;
276
277    ///
278    /// @return true
279    ///
280    bool weighted(void) const;
281
282    ///
283    /// Access operator
284    ///
285    /// @return weight * data for element (@a row, @a column)
286    ///
287    double operator()(const size_t row, const size_t column) const;
288
289    ///
290    /// @brief assigment operator
291    ///
292    /// Does only change MatrixLookupWeighted not the underlying
293    /// matrix object. However if the MatrixLookupWeighted is owner
294    /// (and the only owner) of its underlying data, those data will
295    /// be deleted here.
296    ///
297    const MatrixLookupWeighted& operator=(const MatrixLookupWeighted&);
298   
299  private:
300    const utility::matrix* data_;
301    const utility::matrix* weights_;
302    u_int* ref_count_weights_;
303  }; 
304 
305  ///
306  /// The output operator MatrixLookupWeighted
307  ///
308  /// For eacd data element data(i,j) is printed except those being
309  /// associated with a zero weight for which nothing is printed.
310  ///
311  std::ostream& operator<< (std::ostream& s, const MatrixLookupWeighted&);
312
313}}} // of namespace classifier, yat, and theplu
314
315#endif
Note: See TracBrowser for help on using the repository browser.