source: trunk/c++_tools/classifier/MatrixLookup.h @ 675

Last change on this file since 675 was 675, checked in by Jari Häkkinen, 15 years ago

References #83. Changing project name to yat. Compilation will fail in this revision.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date ID
File size: 8.9 KB
Line 
1#ifndef _theplu_classifier_matrix_lookup_
2#define _theplu_classifier_matrix_lookup_
3
4// $Id$
5
6/*
7  Copyright (C) The authors contributing to this file.
8
9  This file is part of the yat library, http://lev.thep.lu.se/trac/yat
10
11  The yat library is free software; you can redistribute it and/or
12  modify it under the terms of the GNU General Public License as
13  published by the Free Software Foundation; either version 2 of the
14  License, or (at your option) any later version.
15
16  The yat library is distributed in the hope that it will be useful,
17  but WITHOUT ANY WARRANTY; without even the implied warranty of
18  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19  General Public License for more details.
20
21  You should have received a copy of the GNU General Public License
22  along with this program; if not, write to the Free Software
23  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
24  02111-1307, USA.
25*/
26
27#include "yat/classifier/DataLookup2D.h"
28#include "yat/utility/matrix.h"
29
30#include <cassert>
31
32namespace theplu {
33namespace classifier { 
34
35 
36
37  ///
38  /// MatrixLookups can be used to create lookups/views into matrices
39  /// in a more general way than the views supported in the matrix
40  /// class. The object does not contain any data, but only a pointer
41  /// to a matrix and row and columns incices defining which
42  /// sub-matrix to look into.  Each row and each column corresponds
43  /// to a row and a column in the Kernel, respectively. This design
44  /// allow for fast creation of sub-matrices, which is a common
45  /// operation in most traning/validation procedures.
46  ///
47  /// A MatrixLookup can be created directly from a matrix or from an
48  /// other MatrixLookup. In the latter case, the resulting
49  /// MatrixLookup is looking directly into the underlying matrix to
50  /// avoid multiple lookups.
51  ///
52  /// There is a possibility to set the MatrixLookup as owner of the
53  /// underlying matrix.
54  ///
55  class MatrixLookup : public DataLookup2D
56  {
57 
58  public:
59
60
61    ///
62    /// Constructor creating a lookup into the entire @a matrix.
63    /// @param own if true MatrixLookup owns its underlying @a matrix
64    ///
65    /// @note If @a matrix goes out of scope or is deleted, the
66    /// MatrixLookup becomes invalid and the result of further use is
67    /// undefined.
68    ///
69    MatrixLookup(const utility::matrix& matrix, const bool own=false);
70
71    ///
72    /// Constructor creating a lookup into a sub-matrix of @a matrix.
73    /// The @a row and @a column define what sub-matrix to look into,
74    /// in other words, the created MatrixLookup will fullfill the
75    /// following: \f$ MatrixLookup(i,j)=matrix(row[i],column[j])
76    /// \f$. This also means that number of rows in created
77    /// MatrixLookup is equal to size of vector @a row, and number of
78    /// columns is equal to size of vector @a column.
79    ///
80    /// @note If @a matrix goes out of scope or is deleted, the
81    /// MatrixLookup becomes invalid and the result of further use is
82    /// undefined.
83    ///
84    MatrixLookup(const utility::matrix& matrix, const std::vector<size_t>& row, 
85                 const std::vector<size_t>& column);
86
87    ///
88    /// Constructor creating a lookup into a sub-matrix of @a matrix.
89    ///
90    /// If @a row_vectors is true the new MatrixLookup will consist
91    /// of the row vectors defined by @a index. This means that the
92    /// created MatrixLookup will fullfill:
93    /// \f$ MatrixLookup(i,j)=matrix(i,index[j]) \f$
94    ///
95    /// If @a row_vectors is false the new MatrixLookup will be consist
96    /// of the rolumn vectors defined by @a index. This means that the
97    /// created MatrixLookup will fullfill:
98    /// \f$ MatrixLookup(i,j)=matrix(index[i],j) \f$
99    ///
100    /// @note If @a matrix goes out of scope or is deleted, the
101    /// MatrixLookup becomes invalid and the result of further use is
102    /// undefined.
103    ///
104    MatrixLookup(const utility::matrix& matrix, 
105                 const std::vector<size_t>& index, 
106                 const bool row_vectors);
107
108    ///
109    /// @brief Copy constructor.
110    ///
111    /// @note If underlying matrix goes out of scope or is deleted, the
112    /// MatrixLookup becomes invalid and the result of further use is
113    /// undefined.
114    ///
115    MatrixLookup(const MatrixLookup&);
116
117    ///
118    /// Creates a sub-MatrixLookup. The Lookup is independent of
119    /// MatrixLookup @a ml. The MatrixLookup is created to look
120    /// directly into the underlying matrix to avoid multiple lookups.
121    ///
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)=ml(row[i],column[j]) \f$. This
125    /// also means that number of rows in created MatrixLookup is
126    /// equal to size of vector @a row, and number of columns is equal
127    /// to size of vector @a column.
128    ///
129    /// @note If underlying 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 MatrixLookup& ml, const std::vector<size_t>& row, 
134                 const std::vector<size_t>& column);
135
136    ///
137    /// Constructor creating a lookup into a sub-matrix of
138    /// @a ml. The MatrixLookup is created to look directly into the
139    /// underlying matrix to avoid multiple lookups.
140    ///
141    /// If @a row_vectors is true the new MatrixLookup will consist
142    /// of the row vectors defined by @a index. This means that the
143    /// created MatrixLookup will fullfill:
144    /// \f$ MatrixLookup(i,j)=ml(i,index[j])\f$
145    ///
146    /// If @a row_vectors is false the new MatrixLookup will consist
147    /// of the rolumn vectors defined by @a index. This means that the
148    /// created MatrixLookup will fullfill:
149    /// \f$ MatrixLookup(i,j) = ml(index[i],j) \f$
150    ///
151    /// @note If underlying matrix goes out of scope or is deleted, the
152    /// MatrixLookup becomes invalid and the result of further use is
153    /// undefined.
154    ///
155    MatrixLookup(const MatrixLookup& ml, const std::vector<size_t>&, 
156                 const bool row_vectors);
157
158    ///
159    /// Constructor creating a MatrixLookup with @a rows rows, @a
160    /// columns columns, and all values are set to @a value. Created
161    /// MatrixLookup owns its underlying matrix.
162    ///
163    MatrixLookup(const size_t rows, const size_t columns, const double value=0);
164
165    ///
166    /// @brief The istream constructor.
167    ///
168    /// In construction the underlying matrix is created from
169    /// stream. The MatrixLookup will be owner of the underlying
170    /// matrix.
171    ///
172    /// @see matrix(istream&) for details.
173    ///
174    MatrixLookup(std::istream&, char sep='\0');
175
176    ///
177    /// Destructor.
178    ///
179    virtual ~MatrixLookup();
180
181    /**
182       the new MatrixLookup will consist of the rolumn vectors
183       defined by @a index. This means that the returned MatrixLookup
184       will fullfill: \f$ returned(i,j) = original(index[i],j) \f$
185
186       @note If underlying matrix goes out of scope or is deleted, the
187       returned pointer becomes invalid and the result of further use is
188       undefined.
189   
190    */
191    const MatrixLookup* selected(const std::vector<size_t>&) const;
192
193    ///
194    /// The created MatrixLookup corresponds to all rows and the
195    /// columns defined by @a index in the original MatrixLookup. The
196    /// created MatrixLookup will fullfill:
197    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
198    ///
199    /// @return pointer to sub-Lookup of the MatrixLookup
200    ///
201    /// @note If underlying matrix goes out of scope or is deleted, the
202    /// returned pointer becomes invalid and the result of further use is
203    /// undefined.
204    ///
205    /// @Note Returns a dynamically allocated DataLookup2D, which has
206    /// to be deleted by the caller to avoid memory leaks.
207    ///
208    const MatrixLookup* training_data(const std::vector<size_t>& index) const;
209   
210    ///
211    /// The created MatrixLookup corresponds to all rows and the
212    /// columns defined by @a index in the original MatrixLookup. The
213    /// created MatrixLookup will fullfill:
214    /// \f$ novel_ml(i,j)=original(i,index[j]) \f$.
215    ///
216    /// @return pointer to sub-Lookup of the MatrixLookup
217    ///
218    /// @note If underlying matrix goes out of scope or is deleted, the
219    /// returned pointer becomes invalid and the result of further use is
220    /// undefined.
221    ///
222    const MatrixLookup* validation_data(const std::vector<size_t>&,
223                                        const std::vector<size_t>&) const;
224    ///
225    /// @return false
226    ///
227    bool weighted(void) const;
228
229    ///
230    /// Access operator
231    ///
232    /// @return element
233    ///
234    inline double operator()(const size_t row, const size_t column) const
235    { 
236      assert(row<rows());
237      assert(column<columns());
238      return (*data_)(row_index_[row], column_index_[column]); 
239    }
240
241    ///
242    /// @brief assigment operator
243    ///
244    /// Does only change MatrixLookup not the underlying matrix
245    /// object. However if the MatrixLookup is owner of its underlying
246    /// matrix, that matrix will be deleted here.
247    ///
248    const MatrixLookup& operator=(const MatrixLookup&);
249   
250  private:
251    const utility::matrix* data_;
252  }; 
253 
254  ///
255  /// The output operator MatrixLookup
256  ///
257  std::ostream& operator<< (std::ostream& s, const MatrixLookup&);
258
259}} // of namespace classifier and namespace theplu
260
261#endif
Note: See TracBrowser for help on using the repository browser.