source: trunk/yat/classifier/MatrixLookupWeighted.h

Last change on this file was 4019, checked in by Peter, 9 months ago

merge 0.18 into trunk

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