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

Last change on this file since 1105 was 1105, checked in by Peter, 15 years ago

adding iterator typedefs in Lookups

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