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

Last change on this file since 1134 was 1134, checked in by Peter, 13 years ago

using Index class instead of std::vector<size_t>

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