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

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

updating copyright statements

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