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

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

refs #396 - fixing in KernelLookup?

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