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

Last change on this file since 1000 was 1000, checked in by Jari Häkkinen, 14 years ago

trac moved to new location.

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