source: trunk/doc/concepts.doxygen @ 1550

Last change on this file since 1550 was 1550, checked in by Peter, 13 years ago

added value_type

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 10.3 KB
RevLine 
[1069]1// $Id: concepts.doxygen 1550 2008-10-06 13:49:52Z peter $
[1094]2//
[1275]3// Copyright (C) 2008 Peter Johansson, Markus Ringnér
[1094]4//
[1437]5// This file is part of the yat library, http://dev.thep.lu.se/yat
[1094]6//
[1113]7// The yat library is free software; you can redistribute it and/or
[1094]8// modify it under the terms of the GNU General Public License as
[1486]9// published by the Free Software Foundation; either version 3 of the
[1094]10// License, or (at your option) any later version.
11//
12// The yat library is distributed in the hope that it will be useful,
13// but WITHOUT ANY WARRANTY; without even the implied warranty of
14// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15// General Public License for more details.
16//
17// You should have received a copy of the GNU General Public License
[1487]18// along with yat. If not, see <http://www.gnu.org/licenses/>.
[1069]19
[1094]20
[1069]21/**
[1112]22\page Concepts Concepts
[1074]23
[1112]24This page lists all the C++ concepts in the yat project.
[1074]25
[1545]26- \subpage concept_container_2d
[1547]27- \subpage concept_distance
[1545]28- \subpage concept_mutable_container_2d
[1112]29- \subpage concept_neighbor_weighting
[1074]30*/
31
32
33/**
[1545]34\page concept_container_2d Container2D
35
36\section Description
37
[1547]38\ref concept_container_2d is a <a
39href="http://www.sgi.com/tech/stl/Container.html">Container</a> that
40stores elements in a two-dimensional array (columns and rows). It
41provides element access element of a specific row and column, as well
42as iterators than can be used iterate over a specific column or row.
[1545]43
44\section Requirements
45
[1547]46A \ref concept_container_2d provides the following:
[1545]47
[1547]48\subsection Types
49
50<table cellspacing=0>
[1550]51<tr><td>Value type</td><td><tt>X::value_type</tt></td>
52<td>Type of element stored in Container.</td>
53</tr>
[1547]54<tr><td>Const reference type</td><td><tt>X::const_reference</tt></td>
55<td>A type that behaves as const reference to the \ref
56concept_container_2d 's value type.</td>
57</tr>
58<tr>
59<td>Const iterator type</td>
60<td><tt>X::const_iterator</tt></td> 
61<td>
62A read-only iterator that can be used to iterate over the entire \ref
63concept_container_2d. Typically the iterator iterates along a
64row, and when the end of one row is reached it jumps to the
65beginning of the next row.
66</td>
67</tr>
68<tr>
69<td>Const column iterator type</td>
70<td><tt>X::const_column_iterator</tt></td> 
71<td>
72A read-only iterator that can be used to examine the elements in one
73column of the \ref concept_container_2d.
74</td>
75</tr>
76<tr>
77<td>Const row iterator type</td>
78<td><tt>X::const_row_iterator</tt></td> 
79<td>
80A read-only iterator that can be used to examine the elements in one
81row of the \ref concept_container_2d.
82</td>
83</tr>
84</table>
85
86\subsection public_functions Public Functions
87
88<table cellspacing=0>
89<tr>
90<th>Name</th><th>Expression</th><th>Precondition</th><th>Return type</th>
91<th>Postcondition</th>
92</tr>
93<tr>
94<td>Beginning of range</td>
95<td><tt>a.begin()</tt></td>
96<td>&nbsp;</td>
97<td><tt>const_iterator</tt></td>
98<td>&nbsp;</td>
99</tr>
100<tr>
101<td>Beginning of column</td>
102<td><tt>a.begin_column(size_t column)</tt></td>
103<td><tt>0 &lt;= column &lt; a.columns()</tt></td>
104<td><tt>const_column_iterator</tt></td>
105<td>&nbsp;</td>
106</tr>
107<tr>
108<td>Beginning of row</td>
109<td><tt>a.begin_row(size_t row)</tt></td>
110<td><tt>0 &lt;= row &lt; a.rows()</tt></td>
111<td><tt>const_row_iterator</tt></td>
112<td>&nbsp;</td>
113</tr>
114<tr>
115<td>End of range</td>
116<td><tt>a.end()</tt></td>
117<td>&nbsp;</td>
118<td><tt>const_iterator</tt></td>
119<td>&nbsp;</td>
120</tr>
121<tr>
122<td>End of column</td>
123<td><tt>a.end_column(size_t column)</tt></td>
124<td><tt>0 &lt;= column &lt; a.columns()</tt></td>
125<td><tt>const_column_iterator</tt></td>
126<td>&nbsp;</td>
127</tr>
128<tr>
129<td>End of row</td>
130<td><tt>a.end_row(size_t row)</tt></td>
131<td><tt>0 &lt;= row &lt; a.rows()</tt></td>
132<td><tt>const_row_iterator</tt></td>
133<td>&nbsp;</td>
134</tr>
135<tr>
136<td>Columns</td>
137<td><tt>a.columns()</tt></td>
138<td>&nbsp;</td>
139<td><tt>size_t</tt></td>
140<td>&nbsp;</td>
141</tr>
142<tr>
143<td>Rows</td>
144<td><tt>a.rows()</tt></td>
145<td>&nbsp;</td>
146<td><tt>size_t</tt></td>
147<td>&nbsp;</td>
148</tr>
149<tr>
150<td>Element Access</td>
151<td><tt>a(size_t row, size_t column)</tt></td>
152<td><tt>0 &lt;= row&lt;a.rows()</tt> and
153<tt>0 &lt= column &lt; a.columns()</tt></td>
154<td><tt>const_reference</tt></td>
155<td>&nbsp;</td>
156</tr>
157</table>
158
[1545]159\section Implementations
160
[1547]161Examples of concept \ref concept_container_2d include:
162  - theplu::yat::classifier::MatrixLookup,
163  - theplu::yat::classifier::MatrixLookupWeighted
164  - theplu::yat::classifier::KernelLookup.
[1545]165
166*/
167
168/**
[1547]169\page concept_mutable_container_2d Mutable Container2D
[1545]170
171\section Description
172
[1547]173\ref concept_mutable_container_2d is a \ref concept_container_2d that
174also provides non-const access to its elements.
[1545]175
176\section Requirements
177
[1547]178In addition to the requirements defined in \ref concept_container_2d,
179a \ref concept_mutable_container_2d also provides the following:
180
181\subsection Types
182
183<table cellspacing=0>
184<tr><td>Reference type</td><td><tt>X::reference</tt></td>
185<td>A type that behaves as reference to the \ref
186concept_mutable_container_2d 's value type.</td>
187</tr>
188<tr>
189<td>Iterator type</td>
190<td><tt>X::iterator</tt></td> 
191<td>
192
193A mutable iterator similar to Const iterator type, which can be used to
194iterate over the \ref concept_mutable_container_2d (and modify the
195elements). Typically the iterator iterates along a row, and when the
196end of one row is reached it jumps to the beginning of the next row.
197
198</td>
199</tr>
200<tr>
201<td>Column iterator type</td>
202<td><tt>X::column_iterator</tt></td> 
203<td>
204A mutable iterator that can be used to modify the elements in one
205column of the \ref concept_mutable_container_2d.
206</td>
207</tr>
208<tr>
209<td>Row iterator type</td>
210<td><tt>X::row_iterator</tt></td> 
211<td>
212A mutable iterator that can be used to modify the elements in one
213row of the \ref concept_mutable_container_2d.
214</td>
215</tr>
216</table>
217
218\subsection public_functions Public Functions
219
220<table cellspacing=0>
221<tr>
222<th>Name</th><th>Expression</th><th>Precondition</th><th>Return type</th>
223<th>Postcondition</th>
224</tr>
225<tr>
226<td>Beginning of range</td>
227<td><tt>a.begin()</tt></td>
228<td>&nbsp;</td>
229<td><tt>iterator</tt></td>
230<td><tt>iterator</tt> is derefenceable, unless <tt>a</tt> is empty</td>
231</tr>
232<tr>
233<td>Beginning of column</td>
234<td><tt>a.begin_column(size_t column)</tt></td>
235<td><tt>0 &lt;= column &lt; a.columns()</tt></td>
236<td><tt>column_iterator</tt></td>
237<td><tt>column_iterator</tt> is derefenceable, unless <tt>a</tt> is empty</td>
238</tr>
239<tr>
240<td>Beginning of row</td>
241<td><tt>a.begin_row(size_t row)</tt></td>
242<td><tt>0 &lt;= row &lt; a.rows()</tt></td>
243<td><tt>row_iterator</tt></td>
244<td><tt>row_iterator</tt> is derefenceable, unless <tt>a</tt> is empty</td>
245</tr>
246<tr>
247<td>End of range</td>
248<td><tt>a.end()</tt></td>
249<td>&nbsp;</td>
250<td><tt>iterator</tt></td>
251<td>&nbsp;</td>
252</tr>
253<tr>
254<td>End of column</td>
255<td><tt>a.end_column(size_t column)</tt></td>
256<td><tt>column&lt;a.columns()</tt></td>
257<td><tt>column_iterator</tt></td>
258<td>&nbsp;</td>
259</tr>
260<tr>
261<td>End of row</td>
262<td><tt>a.end_row(size_t row)</tt></td>
263<td><tt>row&lt;a.rows()</tt></td>
264<td><tt>row_iterator</tt></td>
265<td>&nbsp;</td>
266</tr>
267<tr>
268<td>Element Access</td>
269<td><tt>a(size_t row, size_t column)</tt></td>
270<td><tt>0 &lt;= row &lt; a.rows()</tt> and
271<tt>0 &lt;= column &lt; a.columns()</tt></td>
272<td><tt>reference</tt></td>
273<td>&nbsp;</td>
274</tr>
275</table>
276
[1545]277\section Implementations
278
[1547]279Examples of concept \ref concept_mutable_container_2d include:
280  - theplu::yat::utility::Matrix,
281  - theplu::yat::utility::MatrixWeighted
[1545]282
283*/
284
285/**
[1112]286\page concept_distance Distance
287
288\section Description
289
[1115]290\ref concept_distance is a concept for classes implementing different
291alternatives to calculate the distance between two points.
[1112]292
293\section Requirements
294
[1115]295Classes modelling the concept \ref concept_distance should implement
296the following public function:
[1112]297
[1115]298\verbatim
299template<typename Iter1, typename Iter2>
300double  operator() (Iter1 beg1, Iter1 end1, Iter2 beg2) const
301\endverbatim
302
303This function should calculate and return the distance between
304elements of two ranges. The first range is given by [\a beg1, \a end1)
305and the second range starts with \a beg2 and has the same length as
306the first range. The function should support iterators of the category
307std::forward_iterator. The function should provide both a fast
308calculation for unweighted iterators and a calculation for weighted
309iterators. The latter correspond to the case where elements in a range
310have both a value and a weight. The selection between unweighted and
311weighted implementations should utilize
[1171]312theplu::yat::utility::unweighted_iterator_tag and
[1115]313theplu::yat::utility::weighted_iterator_tag. Moreover
314theplu::yat::utility::weighted_if_any2 should be utilized to provide a
315weighted implementation if any of the two ranges is weighted, and an
316unweighted implementation when both ranges are unweighted.
317
318\section Implementations
319
[1112]320Examples of classes modelling the concept \ref concept_distance
321include theplu::yat::statistics::PearsonDistance and
322theplu::yat::statistics::EuclideanDistance.
323
[1181]324\see \ref weighted_distance
325
[1073]326*/
[1112]327
328/**
329\page concept_neighbor_weighting Neighbor Weighting Method
330
331\section Description
332
333\ref concept_neighbor_weighting is a concept used in connection with
334theplu::yat::classifier::KNN - classes used as the template argument
335NeighborWeighting should implement this concept.
336
337\section Requirements
338
339Classes modelling the concept \ref concept_neighbor_weighting should
[1115]340implement the following public function:
[1112]341 
342\verbatim   
[1522]343void operator()(const utility::VectorBase& distance,
344                const std::vector<size_t>& k_sorted,
345                const Target& target,
346                utility::VectorMutable& prediction) const
[1112]347\endverbatim
348
349For a test sample, this function should calculate a total vote
350(i.e. based on all k nearest neighbors) for each class. The vector \a
351distance contains the distances from a test sample to all training
352samples. The vector \a k_sorted contains the indices (for both \a
353distance and \a target) to the k training samples with the smallest
354distances to the test sample. The class for each training sample is
355given by \a target, which is sorted in the same sample order as \a
356distance. For each class the function calculates a total vote based on
357the the nearest neighbors of the test sample that belong to the
[1156]358class. The total vote for each class is stored in the vector \a
359prediction.  The function should be implemented such that nearest
360neighbors with distance infinity do not vote.
[1112]361
[1115]362\section Implementations
363
[1112]364Examples of classes modelling the concept \ref
365concept_neighbor_weighting include
366theplu::yat::classifier::KNN_Uniform,
367theplu::yat::classifier::KNN_ReciprocalDistance and
368theplu::yat::classifier::KNN_ReciprocalRank.
369
370*/
Note: See TracBrowser for help on using the repository browser.