source: trunk/yat/classifier/MatrixLookup.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: 11.0 KB
Line 
1#ifndef _theplu_yat_classifier_matrix_lookup_
2#define _theplu_yat_classifier_matrix_lookup_
3
4// $Id$
5
6/*
7  Copyright (C) 2005 Peter Johansson, Markus Ringnér
8  Copyright (C) 2006 Jari Häkkinen, Peter Johansson, Markus Ringnér
9  Copyright (C) 2007, 2008 Jari Häkkinen, Peter Johansson
10  Copyright (C) 2009, 2010, 2012, 2020 Peter Johansson
11
12  This file is part of the yat library, http://dev.thep.lu.se/yat
13
14  The yat library is free software; you can redistribute it and/or
15  modify it under the terms of the GNU General Public License as
16  published by the Free Software Foundation; either version 3 of the
17  License, or (at your option) any later version.
18
19  The yat library is distributed in the hope that it will be useful,
20  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22  General Public License for more details.
23
24  You should have received a copy of the GNU General Public License
25  along with yat. If not, see <http://www.gnu.org/licenses/>.
26*/
27
28#include "yat/utility/Container2DIterator.h"
29#include "yat/utility/deprecate.h"
30#include "yat/utility/Index.h"
31#include "yat/utility/iterator_traits.h"
32#include "yat/utility/Matrix.h"
33
34#include <boost/iterator/permutation_iterator.hpp>
35
36#include <iosfwd>
37#include <memory>
38#include <vector>
39
40namespace theplu {
41namespace yat {
42namespace classifier {
43
44  ///
45  /// @brief General view into utility::Matrix
46  ///
47  /// MatrixLookups can be used to create lookups/views into matrices
48  /// in a more general way than the views supported in the matrix
49  /// class. The object does not contain any data, but only a pointer
50  /// to a utility::Matrix and row and columns incices defining which
51  /// sub-matrix to look into.  Each row and each column corresponds
52  /// to a row and a column in the utility::Matrix, respectively. This design
53  /// allow for fast creation of sub-matrices, which is a common
54  /// operation in most traning/validation procedures. The views are
55  /// const views in the sense that they cannot modify underlying
56  /// utility::Matrix.
57  ///
58  /// A MatrixLookup can be created directly from a utility::Matrix or from
59  /// another MatrixLookup. In the latter case, the resulting
60  /// MatrixLookup is looking directly into the underlying utility::Matrix to
61  /// avoid multiple lookups.
62  ///
63  /// There is a possibility to set the MatrixLookup as owner of the
64  /// underlying utility::Matrix. This implies that underlying data is deleted
65  /// in destructor of MatrixLookup, but only if there is no other
66  /// owner of the underlying data.
67  ///
68  /// \see MatrixLookupWeighted
69  ///
70  class MatrixLookup
71  {
72  public:
73    /**
74       value_type is double
75
76       \since New in yat 0.5
77     */
78    typedef utility::Matrix::value_type value_type;
79
80    /**
81       const_reference type is const double&
82
83       \since New in yat 0.5
84     */
85    typedef utility::Matrix::const_reference const_reference;
86
87    /// 'Read Only' iterator
88    typedef utility::Container2DIterator<const MatrixLookup, const double,
89                                         const_reference>
90    const_iterator;
91
92    /**
93       'Read only' iterator used to iterate over a column
94     */
95    typedef boost::permutation_iterator<utility::Matrix::const_column_iterator,
96                                        utility::Index::const_iterator>
97    const_column_iterator;
98
99    /**
100       'Read only' iterator used to iterate over a row
101     */
102    typedef const_column_iterator const_row_iterator;
103
104    ///
105    /// Constructor creating a lookup into the entire @a matrix.
106    /// \param matrix underlying matrix
107    /// @param own if true MatrixLookup owns its underlying @a matrix
108    ///
109    /// @note If \a own is true and \a matrix is already owned by some
110    /// other object, this will lead to \a matrix having multiple
111    /// owners without the owners being aware of each
112    /// other. Consequently multiple deletion will occur.
113    ///
114    /// @note If @a matrix goes out of scope or is deleted, the
115    /// MatrixLookup becomes invalid and the result of further use is
116    /// undefined.
117    ///
118    MatrixLookup(const utility::Matrix& matrix, const bool own=false);
119
120    ///
121    /// Constructor creating a lookup into a sub-matrix of @a matrix.
122    /// The @a row and @a column define what sub-matrix to look into,
123    /// in other words, the created MatrixLookup will fullfill the
124    /// following: \f$ MatrixLookup(i,j)=matrix(row[i],column[j])
125    /// \f$. This also means that number of rows in created
126    /// MatrixLookup is equal to size of vector @a row, and number of
127    /// columns is equal to size of vector @a column.
128    ///
129    /// @note If @a matrix goes out of scope or is deleted, the
130    /// MatrixLookup becomes invalid and the result of further use is
131    /// undefined.
132    ///
133    MatrixLookup(const utility::Matrix& matrix, const utility::Index& row,
134                 const utility::Index& column);
135
136    ///
137    /// Constructor creating a lookup into a sub-matrix of @a matrix.
138    ///
139    /// If @a row_vectors is true the new MatrixLookup will consist
140    /// of the row vectors defined by @a index. This means that the
141    /// created MatrixLookup will fullfill:
142    /// \f$ MatrixLookup(i,j)=matrix(i,index[j]) \f$
143    ///
144    /// If @a row_vectors is false the new MatrixLookup will be consist
145    /// of the rolumn vectors defined by @a index. This means that the
146    /// created MatrixLookup will fullfill:
147    /// \f$ MatrixLookup(i,j)=matrix(index[i],j) \f$
148    ///
149    /// @note If @a matrix goes out of scope or is deleted, the
150    /// MatrixLookup becomes invalid and the result of further use is
151    /// undefined.
152    ///
153    /// \deprecated Provided for backward compatibility with
154    /// the 0.6 API. Use MatrixLookup(const utility::Matrix&, const
155    /// utility::Index&, const utility::Index&)
156    ///
157    MatrixLookup(const utility::Matrix& matrix,
158                 const utility::Index& index,
159                 const bool row_vectors) YAT_DEPRECATE;
160
161    ///
162    /// @brief Copy constructor.
163    ///
164    /// If \a other is owner of underlying data, constructed
165    /// MatrixLookup will also be set as owner of underlying data.
166    ///
167    /// @note If underlying matrix goes out of scope or is deleted, the
168    /// MatrixLookup becomes invalid and the result of further use is
169    /// undefined.
170    ///
171    MatrixLookup(const MatrixLookup& other);
172
173    ///
174    /// @brief Create a sub-MatrixLookup.
175    ///
176    /// The Lookup is independent of
177    /// MatrixLookup @a ml. The MatrixLookup is created to look
178    /// directly into the underlying matrix to avoid multiple lookups.
179    ///
180    /// If \a ml is owner of underlying data, constructed
181    /// MatrixLookup will also be set as owner of underlying data.
182    ///
183    /// The @a row and @a column define what sub-matrix to look into,
184    /// in other words, the created MatrixLookup will fullfill the
185    /// following: MatrixLookup(i,j)=ml(row[i],column[j]). This
186    /// also means that number of rows in created MatrixLookup is
187    /// equal to size of vector @a row, and number of columns is equal
188    /// to size of vector @a column.
189    ///
190    /// If \a ml is owner of underlying data, constructed
191    /// MatrixLookup will also be set as owner of underlying data.
192    ///
193    /// @note If underlying matrix goes out of scope or is deleted, the
194    /// MatrixLookup becomes invalid and the result of further use is
195    /// undefined.
196    ///
197    MatrixLookup(const MatrixLookup& ml, const utility::Index& row,
198                 const utility::Index& column);
199
200    ///
201    /// Constructor creating a lookup into a sub-matrix of
202    /// @a ml. The MatrixLookup is created to look directly into the
203    /// underlying matrix to avoid multiple lookups.
204    ///
205    /// If @a row_vectors is true the new MatrixLookup will consist
206    /// of the row vectors defined by @a index. This means that the
207    /// created MatrixLookup will fullfill:
208    /// MatrixLookup(i,j)=ml(i,index[j])
209    ///
210    /// If @a row_vectors is false the new MatrixLookup will consist
211    /// of the rolumn vectors defined by @a index. This means that the
212    /// created MatrixLookup will fullfill:
213    /// \f$ MatrixLookup(i,j) = ml(index[i],j) \f$
214    ///
215    /// If \a ml is owner of underlying data, constructed
216    /// MatrixLookup will also be set as owner of underlying data.
217    ///
218    /// @note If underlying matrix goes out of scope or is deleted, the
219    /// MatrixLookup becomes invalid and the result of further use is
220    /// undefined.
221    ///
222    /// \deprecated Provided for backgroundColor compatibility with
223    /// the 0.6 API. Use MatrixLookup(const MatrixLookup&, const
224    /// utility::Index&, const utility::Index&)
225    ///
226    MatrixLookup(const MatrixLookup& ml, const utility::Index&,
227                 const bool row_vectors);
228
229    ///
230    /// Constructor creating a MatrixLookup with @a rows rows, @a
231    /// columns columns, and all values are set to @a value. Created
232    /// MatrixLookup owns its underlying matrix.
233    ///
234    MatrixLookup(const size_t rows, const size_t columns, const double value=0);
235
236    ///
237    /// @brief The istream constructor.
238    ///
239    /// In construction the underlying utility::Matrix is created from
240    /// the stream using utility::Matrix(std::istream&). The
241    /// constructed MatrixLookup will be owner of the underlying
242    /// matrix.
243    ///
244    /// @see Matrix(istream&) for details.
245    ///
246    MatrixLookup(std::istream&, char sep='\0');
247
248    ///
249    /// @brief Destructor.
250    ///
251    /// If ownership is set true and there is no other owner of
252    /// underlying data, underlying data is deleted.
253    ///
254    virtual ~MatrixLookup();
255
256    /**
257       Iterator iterates along a row. When end of row is reached it
258       jumps to beginning of next row.
259
260       \return const_iterator pointing to upper-left element.
261     */
262    const_iterator begin(void) const;
263
264    /**
265       Iterator iterates along a column.
266
267       \return iterator pointing to first element of column \a i.
268     */
269    const_column_iterator begin_column(size_t) const;
270
271    /**
272       Iterator iterates along a column.
273
274       \return const_iterator pointing to first element of column \a i.
275     */
276    const_row_iterator begin_row(size_t) const;
277
278    /**
279       \return number of columns
280    */
281    size_t columns(void) const;
282
283    /**
284       \return const_iterator pointing to end of matrix
285     */
286    const_iterator end(void) const;
287
288    /**
289       \return const_iterator pointing to end of column \a i
290     */
291    const_column_iterator end_column(size_t) const;
292
293    /**
294       \return const_iterator pointing to end of row \a i
295     */
296    const_row_iterator end_row(size_t) const;
297
298    /**
299       \return number of rows
300    */
301    size_t rows(void) const;
302
303    ///
304    /// @return false
305    ///
306    bool weighted(void) const;
307
308    ///
309    /// Access operator
310    ///
311    /// @return element
312    ///
313    const_reference operator()(size_t row, size_t column) const;
314
315    ///
316    /// @brief assigment operator
317    ///
318    /// Does only change MatrixLookup not the underlying matrix
319    /// object. However if the MatrixLookup is owner (and the only owner)
320    /// of its underlying
321    /// matrix, that matrix will be deleted here.
322    ///
323    const MatrixLookup& operator=(const MatrixLookup&);
324
325  private:
326    friend class MatrixLookupWeighted;
327
328    utility::Index column_index_;
329    typedef std::shared_ptr<const utility::Matrix> MatrixP;
330    MatrixP data_;
331    utility::Index row_index_;
332
333    // for assertions
334    bool validate(void) const;
335  };
336
337  ///
338  /// The output operator MatrixLookup
339  ///
340  /// \relates MatrixLookup
341  ///
342  std::ostream& operator<< (std::ostream& s, const MatrixLookup&);
343
344}}} // of namespace classifier, yat, and theplu
345
346#endif
Note: See TracBrowser for help on using the repository browser.