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

Last change on this file since 1565 was 1565, checked in by Peter, 14 years ago

removed Policy from Container2DIterator - refs #398

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