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

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

refs #396

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