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

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

cleaning up some docs and includes

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