source: branches/0.4-stable/yat/classifier/MatrixLookupWeighted.h @ 1392

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

trac has moved

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