source: trunk/yat/classifier/KernelLookup.h @ 865

Last change on this file since 865 was 865, checked in by Peter, 14 years ago

changing URL to http://trac.thep.lu.se/trac/yat

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date ID
File size: 9.8 KB
Line 
1#ifndef _theplu_yat_classifier_kernel_lookup_
2#define _theplu_yat_classifier_kernel_lookup_
3
4// $Id$
5
6/*
7  Copyright (C) 2005 Jari Häkkinen, Peter Johansson
8  Copyright (C) 2006 Jari Häkkinen, Markus Ringnér, Peter Johansson
9  Copyright (C) 2007 Peter Johansson
10
11  This file is part of the yat library, http://trac.thep.lu.se/trac/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 2 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 this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
26  02111-1307, USA.
27*/
28
29#include "Kernel.h"
30#include "DataLookup2D.h"
31#include "MatrixLookup.h"
32
33#include <vector>
34
35namespace theplu {
36namespace yat {
37namespace classifier {
38
39  class KernelFunction;
40
41  ///
42  /// @brief Lookup into Kernel
43  ///
44  /// This is the KernelLookup class to be used together with kernel
45  /// methods such as Support Vector Machines (SVM). The class does
46  /// not contain any data or values, but rather is a lookup into a
47  /// Kernel object. Each row and each column corresponds to a row and
48  /// a column in the Kernel, respectively. This design allow for fast
49  /// creation of sub-kernels, which is a common operation in most
50  /// traning/validation procedures.
51  ///
52  /// A KernelLookup can be created directly from a Kernel or from an
53  /// other KernelLookup. In the latter case, the resulting
54  /// KernelLookup is looking directly into the underlying Kernel to
55  /// avoid multiple lookups.
56  ///
57  /// There is a possibility to set the KernelLookup as owner of the
58  /// underlying kernel. This implies that underlying kernel is deleted
59  /// in destructor of MatrixLookup, but only if there is no other
60  /// owner of the underlying kernel. A reference counter is used to
61  /// keep track of number of owners. Ownership is copied in copy
62  /// constructors and assignments.
63  ///
64  class KernelLookup : public DataLookup2D
65  {
66
67  public:
68
69    ///
70    /// @brief Constructor a Lookup into a Kernel
71    ///
72    /// Constructs a KernelLookup corresponding to the Kernel @a
73    /// kernel. By default @a owner is set to false, which means
74    /// KernelLookup does not own the underlying Kernel.
75    ///
76    /// @note If underlying Kernel goes out of scope or is deleted, the
77    /// KernelLookup becomes invalid and the result of further use is
78    /// undefined.
79    ///
80    /// @note Do not construct two KernelLookups from the same @a
81    /// kernel with @a owner set to true because that will cause
82    /// multiple deletion of @a kernel.
83    ///
84    KernelLookup(const Kernel& kernel, const bool owner=false);
85
86    ///
87    /// @brief Constructing a Lookup into a subKernel
88    ///
89    /// Creating a Lookup into parts of the Kernel. In the created
90    /// Lookup the element in the \f$ i \f$ th row in the \f$ j \f$ th
91    /// column is identical to the element in row row[i] and columns
92    /// column[j] in the underlying @a kernel. If @a owner is set to
93    /// true yhe underlying @a kernel is destroyed in the destructor.
94    ///
95    /// @note If @a kernel goes out of scope or is deleted, the
96    /// returned pointer becomes invalid and the result of further use is
97    /// undefined.
98    ///
99    /// @note For training usage row index shall always be equal to
100    /// column index.
101    ///
102    KernelLookup(const Kernel& kernel, const std::vector<size_t>& row, 
103                 const std::vector<size_t>& column, const bool owner=false);
104
105    ///
106    /// @brief Copy constructor.
107    ///
108    /// A Lookup is created looking into the
109    /// same underlying Kernel as @a kl is looking into.
110    ///
111    /// If \a kl is owner of underlying data, constructed
112    /// KernelLookup will also be set as owner of underlying data.
113    ///
114    KernelLookup(const KernelLookup& kl);
115
116
117    ///
118    /// @brief Contructing a sub-KernelLookup.
119    ///
120    /// Contructor building a sub-KernelLookup from a KernelLookup
121    /// defined by row index vector and column index vector. In the
122    /// created Lookup the element in the \f$ i \f$ th row in the
123    /// \f$ j \f$ th column is identical to the element in row row[i] and
124    /// columns column[j] in the copied @a kl. The resulting
125    /// KernelLookup is independent of the old KernelLookup, but is
126    /// undefined in case underlying Kernel is destroyed.
127    ///
128    /// If \a kl is owner of underlying data, constructed
129    /// KernelLookup will also be set as owner of underlying data.
130    ///
131    /// @note For training usage row index shall always be equal to
132    /// column index.
133    ///
134    KernelLookup(const KernelLookup& kl, const std::vector<size_t>& row, 
135                 const std::vector<size_t>& column);
136
137    ///
138    /// Constructor taking the column (default) or row index vector as
139    /// input. If @a row is false the created KernelLookup will have
140    /// equally many rows as @a kernel.
141    ///
142    /// If \a kl is owner of underlying data, constructed
143    /// KernelLookup will also be set as owner of underlying data.
144    ///
145    /// @note If underlying kernel goes out of scope or is deleted, the
146    /// KernelLookup becomes invalid and the result of further use is
147    /// undefined.
148    ///
149    KernelLookup(const KernelLookup& kernel, const std::vector<size_t>&, 
150                 const bool row=false);
151
152    ///
153    /// @brief Destructor
154    ///
155    /// Deletes underlying Kernel if KernelLookup owns it and there is
156    /// no other owner.
157    ///
158    virtual ~KernelLookup(void);
159
160    ///
161    /// Each column in returned DataLookup corresponds to the column
162    /// in KernelLookup.
163    ///
164    /// \return data that KernelLookup is built upon.
165    ///
166    /// @Note Returns a dynamically allocated MatrixLookup, which has
167    /// to be deleted by the caller to avoid memory leaks.
168    ///
169    const DataLookup2D* data(void) const;
170
171    /**
172       Function to calculate a new Kernel element using the underlying
173       KernelFunction. The value is calculated between @a vec and the
174       data vector of the \a i th sample, in other words, the
175       sample corresponding to the \a i th row.
176    */
177    double element(const DataLookup1D& vec, size_t i) const;
178
179    /**
180       Function to calculate a new Kernel element using the underlying
181       KernelFunction. The value is calulated between @a vec and the
182       data vector of the \f$ i \f$ th sample, in other words, the
183       sample corresponding to the \f$ i \f$ th row or \f$ i \f$ th
184       column. In case KernelLookup is a sub-Kernel and not symmetric,
185       the kernel value is calculated between @a vec and the data
186       vector corresponding to \f$ i \f$ th row.
187    */
188    double element(const DataLookupWeighted1D& vec, size_t i) const;
189
190    /**
191       Each element in returned KernelLookup is calculated using only
192       selected features (defined by @a index). Each element
193       corresponds to the same pair of samples as in the original
194       KernelLookup.
195
196       \Note Returns a dynamically allocated KernelLookup, which has
197       to be deleted by the caller to avoid memory leaks.
198    */
199    const KernelLookup* selected(const std::vector<size_t>& index) const;
200   
201    /**
202       This function is useful when predicting on an independent data
203       set using a kernel-based classifier. In returned KernelLookup
204       column \f$ i \f$ corresponds to column \f$ i \f$ in @a
205       data. Row \f$ i \f$ in returned KernelLookup corresponds to
206       same sample as row \f$ i \f$ in @a this. In other words, this
207       function returns a KernelLookup containing the kernel elements
208       between the passed @a data and the internal underlying data @a
209       this was built from.
210   
211       @Note Returns a dynamically allocated DataLookup2D, which has
212       to be deleted by the caller to avoid memory leaks.
213    */
214    const KernelLookup* test_kernel(const MatrixLookup& data) const;
215
216    /**
217       This function is useful when predicting on an independent data
218       set using a kernel-based classifier. In returned KernelLookup
219       column \f$ i \f$ corresponds to column \f$ i \f$ in @a
220       data. Row \f$ i \f$ in returned KernelLookup corresponds to
221       same sample as row \f$ i \f$ in @a this. In other words, this
222       function returns a KernelLookup containing the kernel elements
223       between the passed @a data and the internal underlying data @a
224       this was built from.
225   
226       @Note Returns a dynamically allocated DataLookup2D, which has
227       to be deleted by the caller to avoid memory leaks.
228    */
229    const KernelLookup* test_kernel(const MatrixLookupWeighted& data) const;
230
231    /**
232       \brief Creates a sub-Kernel identical to the one created using
233       KernelLookup(*this, train, train).
234   
235       \return pointer to dynamically allocated sub-Lookup of the
236       KernelLookup
237   
238       \Note Returns a dynamically allocated DataLookup2D, which has
239       to be deleted by the caller to avoid memory leaks.
240    */
241    const KernelLookup* training_data(const std::vector<size_t>& train) const;
242
243    /**
244       In returned kernel each row corresponds to a training sample
245       and each column corresponds to a validation sample. The created
246       sub-KernelLookup is equivalent to using KernelLooup(*this,
247       train, validation).
248   
249       \return sub-Lookup of the DataLookup2D
250   
251       \Note Returns a dynamically allocated DataLookup2D, which has
252       to be deleted by the caller to avoid memory leaks.
253    */
254    const KernelLookup* 
255    validation_data(const std::vector<size_t>& train, 
256                    const std::vector<size_t>& validation) const;
257
258    /**
259       \return true if underlying Kernel is weighted
260    */
261    bool weighted(void) const;
262
263    /**
264       \return element at position (\a row, \a column) in the Kernel
265       matrix
266    */
267    double operator()(size_t row, size_t column) const;
268
269  private:
270    const KernelLookup& operator=(const KernelLookup&);
271
272    const Kernel* kernel_;
273   
274  }; // class KernelLookup
275
276}}} // of namespace classifier, yat, and theplu
277
278#endif
Note: See TracBrowser for help on using the repository browser.