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

Last change on this file since 1035 was 1035, checked in by Peter, 14 years ago

Constructor creating a MatrixLookupWeighted? from MatrixLookup?

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