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

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

removing DataLookup2D closes ticket:243

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