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

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

changing operator() in weighted lookups and removing operator[] in 1D lookups

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