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

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

working on ticket:234

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date ID
File size: 11.4 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, 2008 Peter Johansson
10
11  This file is part of the yat library, http://trac.thep.lu.se/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#include "yat/utility/Container2DIterator.h"
33#include "yat/utility/Index.h"
34#include "yat/utility/iterator_traits.h"
35#include "yat/utility/SmartPtr.h"
36#include "yat/utility/StrideIterator.h"
37
38namespace theplu {
39namespace yat {
40  namespace utility{
41    class Index;
42  }
43namespace classifier {
44
45  class KernelFunction;
46
47  ///
48  /// @brief Lookup into Kernel
49  ///
50  /// This is the KernelLookup class to be used together with kernel
51  /// methods such as Support Vector Machines (SVM). The class does
52  /// not contain any data or values, but rather is a lookup into a
53  /// Kernel object. Each row and each column corresponds to a row and
54  /// a column in the Kernel, respectively. This design allow for fast
55  /// creation of sub-kernels, which is a common operation in most
56  /// traning/validation procedures.
57  ///
58  /// A KernelLookup can be created directly from a Kernel or from an
59  /// other KernelLookup. In the latter case, the resulting
60  /// KernelLookup is looking directly into the underlying Kernel to
61  /// avoid multiple lookups.
62  ///
63  /// There is a possibility to set the KernelLookup as owner of the
64  /// underlying kernel. This implies that underlying kernel is deleted
65  /// in destructor of MatrixLookup, but only if there is no other
66  /// owner of the underlying kernel. A reference counter is used to
67  /// keep track of number of owners. Ownership is copied in copy
68  /// constructors and assignments.
69  ///
70  class KernelLookup
71  {
72
73  public:
74    /// 'Read Only' iterator
75    typedef utility::StrideIterator<
76    utility::Container2DIterator<const KernelLookup, const double, void, 
77                                 const double> >
78    const_iterator;
79
80    /**
81       'Read only' iterator intended to iterate over a column
82     */
83    typedef const_iterator const_column_iterator;
84
85    /**
86       'Read only' iterator intended to iterate over a row
87     */
88    typedef const_iterator const_row_iterator;
89
90    ///
91    /// @brief Constructor a Lookup into a Kernel
92    ///
93    /// Constructs a KernelLookup corresponding to the Kernel @a
94    /// kernel. By default @a owner is set to false, which means
95    /// KernelLookup does not own the underlying Kernel.
96    ///
97    /// @note If underlying Kernel goes out of scope or is deleted, the
98    /// KernelLookup becomes invalid and the result of further use is
99    /// undefined.
100    ///
101    /// @note Do not construct two KernelLookups from the same @a
102    /// kernel with @a owner set to true because that will cause
103    /// multiple deletion of @a kernel.
104    ///
105    KernelLookup(const Kernel& kernel, const bool owner=false);
106
107    ///
108    /// @brief Constructing a Lookup into a subKernel
109    ///
110    /// Creating a Lookup into parts of the Kernel. In the created
111    /// Lookup the element in the \f$ i \f$ th row in the \f$ j \f$ th
112    /// column is identical to the element in row row[i] and columns
113    /// column[j] in the underlying @a kernel. If @a owner is set to
114    /// true yhe underlying @a kernel is destroyed in the destructor.
115    ///
116    /// @note If @a kernel goes out of scope or is deleted, the
117    /// returned pointer becomes invalid and the result of further use is
118    /// undefined.
119    ///
120    /// @note For training usage row Index shall always be equal to
121    /// column Index.
122    ///
123    KernelLookup(const Kernel& kernel, const utility::Index& row, 
124                 const utility::Index& column, const bool owner=false);
125
126    ///
127    /// @brief Copy constructor.
128    ///
129    /// A Lookup is created looking into the
130    /// same underlying Kernel as @a kl is looking into.
131    ///
132    /// If \a kl is owner of underlying data, constructed
133    /// KernelLookup will also be set as owner of underlying data.
134    ///
135    KernelLookup(const KernelLookup& kl);
136
137
138    ///
139    /// @brief Contructing a sub-KernelLookup.
140    ///
141    /// Contructor building a sub-KernelLookup from a KernelLookup
142    /// defined by row index and column index. In the
143    /// created Lookup the element in the \f$ i \f$ th row in the
144    /// \f$ j \f$ th column is identical to the element in row row[i] and
145    /// columns column[j] in the copied @a kl. The resulting
146    /// KernelLookup is independent of the old KernelLookup, but is
147    /// undefined in case underlying Kernel is destroyed.
148    ///
149    /// If \a kl is owner of underlying data, constructed
150    /// KernelLookup will also be set as owner of underlying data.
151    ///
152    /// @note For training usage row index shall always be equal to
153    /// column index.
154    ///
155    KernelLookup(const KernelLookup& kl, const utility::Index& row, 
156                 const utility::Index& column);
157
158    ///
159    /// Constructor taking the column (default) or row Index as
160    /// input. If @a row is false the created KernelLookup will have
161    /// equally many rows as @a kernel.
162    ///
163    /// If \a kl is owner of underlying data, constructed
164    /// KernelLookup will also be set as owner of underlying data.
165    ///
166    /// @note If underlying kernel goes out of scope or is deleted, the
167    /// KernelLookup becomes invalid and the result of further use is
168    /// undefined.
169    ///
170    KernelLookup(const KernelLookup& kernel, const utility::Index&, 
171                 const bool row=false);
172
173    ///
174    /// @brief Destructor
175    ///
176    /// Deletes underlying Kernel if KernelLookup owns it and there is
177    /// no other owner.
178    ///
179    virtual ~KernelLookup(void);
180
181    /**
182       Iterator iterates along a row. When end of row is reached it
183       jumps to beginning of next row.
184
185       \return const_iterator pointing to upper-left element.
186     */
187    const_iterator begin(void) const;
188
189    /**
190       Iterator iterates along a column.
191
192       \return iterator pointing to first element of column \a i.
193     */
194    const_column_iterator begin_column(size_t) const;
195
196    /**
197       Iterator iterates along a column.
198
199       \return const_iterator pointing to first element of column \a i.
200     */
201    const_row_iterator begin_row(size_t) const;
202
203    /**
204       \return Number of columns
205    */
206    size_t columns(void) const;
207
208    ///
209    /// Each column in returned DataLookup corresponds to the column
210    /// in KernelLookup.
211    ///
212    /// \return data that KernelLookup is built upon.
213    ///
214    /// @note Returns a dynamically allocated MatrixLookup, which has
215    /// to be deleted by the caller to avoid memory leaks.
216    ///
217    const DataLookup2D* data(void) const;
218
219    /**
220       Function to calculate a new Kernel element using the underlying
221       KernelFunction. The value is calculated between @a vec and the
222       data vector of the \a i th sample, in other words, the
223       sample corresponding to the \a i th row.
224    */
225    double element(const DataLookup1D& vec, size_t i) const;
226
227    /**
228       Function to calculate a new Kernel element using the underlying
229       KernelFunction. The value is calulated between @a vec and the
230       data vector of the \f$ i \f$ th sample, in other words, the
231       sample corresponding to the \f$ i \f$ th row or \f$ i \f$ th
232       column. In case KernelLookup is a sub-Kernel and not symmetric,
233       the kernel value is calculated between @a vec and the data
234       vector corresponding to \f$ i \f$ th row.
235    */
236    double element(const DataLookupWeighted1D& vec, size_t i) const;
237
238    /**
239       \return const_iterator pointing to end of matrix
240     */
241    const_iterator end(void) const;
242
243    /**
244       \return const_iterator pointing to end of column \a i
245     */
246    const_column_iterator end_column(size_t) const;
247
248    /**
249       \return const_iterator pointing to end of row \a i
250     */
251    const_row_iterator end_row(size_t) const;
252
253    /**
254       \return Number of columns
255    */
256    size_t rows(void) const;
257
258    /**
259       Each element in returned KernelLookup is calculated using only
260       selected features (defined by @a index). Each element
261       corresponds to the same pair of samples as in the original
262       KernelLookup.
263
264       \note Returns a dynamically allocated KernelLookup, which has
265       to be deleted by the caller to avoid memory leaks.
266    */
267    const KernelLookup* selected(const utility::Index& index) const;
268   
269    /**
270       This function is useful when predicting on an independent data
271       set using a kernel-based classifier. In returned KernelLookup
272       column \f$ i \f$ corresponds to column \f$ i \f$ in @a
273       data. Row \f$ i \f$ in returned KernelLookup corresponds to
274       same sample as row \f$ i \f$ in @a this. In other words, this
275       function returns a KernelLookup containing the kernel elements
276       between the passed @a data and the internal underlying data @a
277       this was built from.
278   
279       @note Returns a dynamically allocated DataLookup2D, which has
280       to be deleted by the caller to avoid memory leaks.
281    */
282    const KernelLookup* test_kernel(const MatrixLookup& data) const;
283
284    /**
285       This function is useful when predicting on an independent data
286       set using a kernel-based classifier. In returned KernelLookup
287       column \f$ i \f$ corresponds to column \f$ i \f$ in @a
288       data. Row \f$ i \f$ in returned KernelLookup corresponds to
289       same sample as row \f$ i \f$ in @a this. In other words, this
290       function returns a KernelLookup containing the kernel elements
291       between the passed @a data and the internal underlying data @a
292       this was built from.
293   
294       @note Returns a dynamically allocated DataLookup2D, which has
295       to be deleted by the caller to avoid memory leaks.
296    */
297    const KernelLookup* test_kernel(const MatrixLookupWeighted& data) const;
298
299    /**
300       \brief Creates a sub-Kernel identical to the one created using
301       KernelLookup(*this, train, train).
302   
303       \return pointer to dynamically allocated sub-Lookup of the
304       KernelLookup
305   
306       \note Returns a dynamically allocated DataLookup2D, which has
307       to be deleted by the caller to avoid memory leaks.
308    */
309    const KernelLookup* training_data(const std::vector<size_t>& train) const;
310
311    /**
312       In returned kernel each row corresponds to a training sample
313       and each column corresponds to a validation sample. The created
314       sub-KernelLookup is equivalent to using KernelLooup(*this,
315       train, validation).
316   
317       \return sub-Lookup of the DataLookup2D
318   
319       \note Returns a dynamically allocated DataLookup2D, which has
320       to be deleted by the caller to avoid memory leaks.
321    */
322    const KernelLookup* 
323    validation_data(const std::vector<size_t>& train, 
324                    const std::vector<size_t>& validation) const;
325
326    /**
327       \return true if underlying Kernel is weighted
328    */
329    bool weighted(void) const;
330
331    /**
332       \return element at position (\a row, \a column) in the Kernel
333       matrix
334    */
335    double operator()(size_t row, size_t column) const;
336
337  private:
338    const KernelLookup& operator=(const KernelLookup&);
339
340    utility::Index column_index_;
341    utility::SmartPtr<const Kernel> kernel_;
342    utility::Index row_index_;
343   
344  }; // class KernelLookup
345
346}}} // of namespace classifier, yat, and theplu
347
348#endif
Note: See TracBrowser for help on using the repository browser.