source: trunk/yat/classifier/MatrixLookup.h @ 757

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

Fixed #include statemenst and forward declarations. asserts in headers removed.

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