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

Last change on this file since 767 was 767, checked in by Peter, 15 years ago

Fixes #65

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