doc/concepts.doxygen

Code
Comments
Other
Rev Date Author Line
1069 11 Feb 08 markus 1 // $Id$
1094 15 Feb 08 peter 2 //
2119 12 Dec 09 peter 3 // Copyright (C) 2008 Jari Häkkinen, Peter Johansson, Markus Ringnér
3550 03 Jan 17 peter 4 // Copyright (C) 2009, 2010, 2011, 2014, 2017 Peter Johansson
1094 15 Feb 08 peter 5 //
1437 25 Aug 08 peter 6 // This file is part of the yat library, http://dev.thep.lu.se/yat
1094 15 Feb 08 peter 7 //
1113 21 Feb 08 peter 8 // The yat library is free software; you can redistribute it and/or
1094 15 Feb 08 peter 9 // modify it under the terms of the GNU General Public License as
1486 09 Sep 08 jari 10 // published by the Free Software Foundation; either version 3 of the
1094 15 Feb 08 peter 11 // License, or (at your option) any later version.
1094 15 Feb 08 peter 12 //
1094 15 Feb 08 peter 13 // The yat library is distributed in the hope that it will be useful,
1094 15 Feb 08 peter 14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
1094 15 Feb 08 peter 15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1094 15 Feb 08 peter 16 // General Public License for more details.
1094 15 Feb 08 peter 17 //
1094 15 Feb 08 peter 18 // You should have received a copy of the GNU General Public License
1487 10 Sep 08 jari 19 // along with yat. If not, see <http://www.gnu.org/licenses/>.
1069 11 Feb 08 markus 20
1094 15 Feb 08 peter 21
1069 11 Feb 08 markus 22 /**
1112 21 Feb 08 markus 23 \page Concepts Concepts
1074 12 Feb 08 markus 24
1112 21 Feb 08 markus 25 This page lists all the C++ concepts in the yat project.
1074 12 Feb 08 markus 26
1545 01 Oct 08 peter 27 - \subpage concept_container_2d
2141 12 Jan 10 peter 28 - \subpage concept_data_iterator
1547 03 Oct 08 peter 29 - \subpage concept_distance
1545 01 Oct 08 peter 30 - \subpage concept_mutable_container_2d
1112 21 Feb 08 markus 31 - \subpage concept_neighbor_weighting
1590 17 Oct 08 peter 32 - \subpage concept_weighted_iterator
1074 12 Feb 08 markus 33 */
1074 12 Feb 08 markus 34
1074 12 Feb 08 markus 35
1074 12 Feb 08 markus 36 /**
1545 01 Oct 08 peter 37 \page concept_container_2d Container2D
1545 01 Oct 08 peter 38
3295 25 Jul 14 peter 39 \section concept_container_2d_description Description
1545 01 Oct 08 peter 40
1547 03 Oct 08 peter 41 \ref concept_container_2d is a <a
1547 03 Oct 08 peter 42 href="http://www.sgi.com/tech/stl/Container.html">Container</a> that
1547 03 Oct 08 peter 43 stores elements in a two-dimensional array (columns and rows). It
2002 13 Jun 09 peter 44 provides element access of a specific row and column, as well
1699 06 Jan 09 peter 45 as iterators that can be used to iterate over a specific column or
1699 06 Jan 09 peter 46 row.
1545 01 Oct 08 peter 47
3295 25 Jul 14 peter 48 \section concept_container_2d_requirments Requirements
1545 01 Oct 08 peter 49
1547 03 Oct 08 peter 50 A \ref concept_container_2d provides the following:
1545 01 Oct 08 peter 51
3295 25 Jul 14 peter 52 \subsection concept_container_2d_types Types
1547 03 Oct 08 peter 53
2299 12 Jul 10 peter 54 <table cellspacing=0 border=1>
1550 06 Oct 08 peter 55 <tr><td>Value type</td><td><tt>X::value_type</tt></td>
1550 06 Oct 08 peter 56 <td>Type of element stored in Container.</td>
1550 06 Oct 08 peter 57 </tr>
1547 03 Oct 08 peter 58 <tr><td>Const reference type</td><td><tt>X::const_reference</tt></td>
1547 03 Oct 08 peter 59 <td>A type that behaves as const reference to the \ref
1547 03 Oct 08 peter 60 concept_container_2d 's value type.</td>
1547 03 Oct 08 peter 61 </tr>
1547 03 Oct 08 peter 62 <tr>
1547 03 Oct 08 peter 63 <td>Const iterator type</td>
3295 25 Jul 14 peter 64 <td><tt>X::const_iterator</tt></td>
1547 03 Oct 08 peter 65 <td>
1547 03 Oct 08 peter 66 A read-only iterator that can be used to iterate over the entire \ref
1547 03 Oct 08 peter 67 concept_container_2d. Typically the iterator iterates along a
1547 03 Oct 08 peter 68 row, and when the end of one row is reached it jumps to the
1547 03 Oct 08 peter 69 beginning of the next row.
1547 03 Oct 08 peter 70 </td>
1547 03 Oct 08 peter 71 </tr>
1547 03 Oct 08 peter 72 <tr>
1547 03 Oct 08 peter 73 <td>Const column iterator type</td>
3295 25 Jul 14 peter 74 <td><tt>X::const_column_iterator</tt></td>
1547 03 Oct 08 peter 75 <td>
1547 03 Oct 08 peter 76 A read-only iterator that can be used to examine the elements in one
1547 03 Oct 08 peter 77 column of the \ref concept_container_2d.
1547 03 Oct 08 peter 78 </td>
1547 03 Oct 08 peter 79 </tr>
1547 03 Oct 08 peter 80 <tr>
1547 03 Oct 08 peter 81 <td>Const row iterator type</td>
3295 25 Jul 14 peter 82 <td><tt>X::const_row_iterator</tt></td>
1547 03 Oct 08 peter 83 <td>
1547 03 Oct 08 peter 84 A read-only iterator that can be used to examine the elements in one
1547 03 Oct 08 peter 85 row of the \ref concept_container_2d.
1547 03 Oct 08 peter 86 </td>
1547 03 Oct 08 peter 87 </tr>
1547 03 Oct 08 peter 88 </table>
1547 03 Oct 08 peter 89
3295 25 Jul 14 peter 90 \subsection concept_container_2d_public_functions Public Functions
1547 03 Oct 08 peter 91
2299 12 Jul 10 peter 92 <table cellspacing=0 border=1>
1547 03 Oct 08 peter 93 <tr>
1547 03 Oct 08 peter 94 <th>Name</th><th>Expression</th><th>Precondition</th><th>Return type</th>
1547 03 Oct 08 peter 95 <th>Postcondition</th>
1547 03 Oct 08 peter 96 </tr>
1547 03 Oct 08 peter 97 <tr>
1547 03 Oct 08 peter 98 <td>Beginning of range</td>
1547 03 Oct 08 peter 99 <td><tt>a.begin()</tt></td>
1547 03 Oct 08 peter 100 <td>&nbsp;</td>
1547 03 Oct 08 peter 101 <td><tt>const_iterator</tt></td>
1547 03 Oct 08 peter 102 <td>&nbsp;</td>
1547 03 Oct 08 peter 103 </tr>
1547 03 Oct 08 peter 104 <tr>
1547 03 Oct 08 peter 105 <td>Beginning of column</td>
1547 03 Oct 08 peter 106 <td><tt>a.begin_column(size_t column)</tt></td>
1547 03 Oct 08 peter 107 <td><tt>0 &lt;= column &lt; a.columns()</tt></td>
1547 03 Oct 08 peter 108 <td><tt>const_column_iterator</tt></td>
1547 03 Oct 08 peter 109 <td>&nbsp;</td>
1547 03 Oct 08 peter 110 </tr>
1547 03 Oct 08 peter 111 <tr>
1547 03 Oct 08 peter 112 <td>Beginning of row</td>
1547 03 Oct 08 peter 113 <td><tt>a.begin_row(size_t row)</tt></td>
1547 03 Oct 08 peter 114 <td><tt>0 &lt;= row &lt; a.rows()</tt></td>
1547 03 Oct 08 peter 115 <td><tt>const_row_iterator</tt></td>
1547 03 Oct 08 peter 116 <td>&nbsp;</td>
1547 03 Oct 08 peter 117 </tr>
1547 03 Oct 08 peter 118 <tr>
1547 03 Oct 08 peter 119 <td>End of range</td>
1547 03 Oct 08 peter 120 <td><tt>a.end()</tt></td>
1547 03 Oct 08 peter 121 <td>&nbsp;</td>
1547 03 Oct 08 peter 122 <td><tt>const_iterator</tt></td>
1547 03 Oct 08 peter 123 <td>&nbsp;</td>
1547 03 Oct 08 peter 124 </tr>
1547 03 Oct 08 peter 125 <tr>
1547 03 Oct 08 peter 126 <td>End of column</td>
1547 03 Oct 08 peter 127 <td><tt>a.end_column(size_t column)</tt></td>
1547 03 Oct 08 peter 128 <td><tt>0 &lt;= column &lt; a.columns()</tt></td>
1547 03 Oct 08 peter 129 <td><tt>const_column_iterator</tt></td>
1547 03 Oct 08 peter 130 <td>&nbsp;</td>
1547 03 Oct 08 peter 131 </tr>
1547 03 Oct 08 peter 132 <tr>
1547 03 Oct 08 peter 133 <td>End of row</td>
1547 03 Oct 08 peter 134 <td><tt>a.end_row(size_t row)</tt></td>
1547 03 Oct 08 peter 135 <td><tt>0 &lt;= row &lt; a.rows()</tt></td>
1547 03 Oct 08 peter 136 <td><tt>const_row_iterator</tt></td>
1547 03 Oct 08 peter 137 <td>&nbsp;</td>
1547 03 Oct 08 peter 138 </tr>
1547 03 Oct 08 peter 139 <tr>
1547 03 Oct 08 peter 140 <td>Columns</td>
1547 03 Oct 08 peter 141 <td><tt>a.columns()</tt></td>
1547 03 Oct 08 peter 142 <td>&nbsp;</td>
1547 03 Oct 08 peter 143 <td><tt>size_t</tt></td>
1547 03 Oct 08 peter 144 <td>&nbsp;</td>
1547 03 Oct 08 peter 145 </tr>
1547 03 Oct 08 peter 146 <tr>
1547 03 Oct 08 peter 147 <td>Rows</td>
1547 03 Oct 08 peter 148 <td><tt>a.rows()</tt></td>
1547 03 Oct 08 peter 149 <td>&nbsp;</td>
1547 03 Oct 08 peter 150 <td><tt>size_t</tt></td>
1547 03 Oct 08 peter 151 <td>&nbsp;</td>
1547 03 Oct 08 peter 152 </tr>
1547 03 Oct 08 peter 153 <tr>
1547 03 Oct 08 peter 154 <td>Element Access</td>
1547 03 Oct 08 peter 155 <td><tt>a(size_t row, size_t column)</tt></td>
3295 25 Jul 14 peter 156 <td><tt>0 &lt;= row &lt; a.rows()</tt> and
1698 06 Jan 09 peter 157 <tt>0 &lt;= column &lt; a.columns()</tt></td>
1547 03 Oct 08 peter 158 <td><tt>const_reference</tt></td>
1547 03 Oct 08 peter 159 <td>&nbsp;</td>
1547 03 Oct 08 peter 160 </tr>
1547 03 Oct 08 peter 161 </table>
1547 03 Oct 08 peter 162
3295 25 Jul 14 peter 163 \section concept_container_2d_implementations Implementations
1545 01 Oct 08 peter 164
1547 03 Oct 08 peter 165 Examples of concept \ref concept_container_2d include:
1547 03 Oct 08 peter 166   - theplu::yat::classifier::MatrixLookup,
1547 03 Oct 08 peter 167   - theplu::yat::classifier::MatrixLookupWeighted
1547 03 Oct 08 peter 168   - theplu::yat::classifier::KernelLookup.
1545 01 Oct 08 peter 169
1545 01 Oct 08 peter 170 */
1545 01 Oct 08 peter 171
1545 01 Oct 08 peter 172 /**
1547 03 Oct 08 peter 173 \page concept_mutable_container_2d Mutable Container2D
1545 01 Oct 08 peter 174
3295 25 Jul 14 peter 175 \section concept_mutable_container_2d_description Description
1545 01 Oct 08 peter 176
1547 03 Oct 08 peter 177 \ref concept_mutable_container_2d is a \ref concept_container_2d that
1547 03 Oct 08 peter 178 also provides non-const access to its elements.
1545 01 Oct 08 peter 179
3295 25 Jul 14 peter 180 \section concept_mutable_container_2d_requirments Requirements
1545 01 Oct 08 peter 181
1547 03 Oct 08 peter 182 In addition to the requirements defined in \ref concept_container_2d,
1547 03 Oct 08 peter 183 a \ref concept_mutable_container_2d also provides the following:
1547 03 Oct 08 peter 184
3295 25 Jul 14 peter 185 \subsection concept_mutable_container_2d_types Types
1547 03 Oct 08 peter 186
2299 12 Jul 10 peter 187 <table cellspacing=0 border=1>
1547 03 Oct 08 peter 188 <tr><td>Reference type</td><td><tt>X::reference</tt></td>
1547 03 Oct 08 peter 189 <td>A type that behaves as reference to the \ref
1547 03 Oct 08 peter 190 concept_mutable_container_2d 's value type.</td>
1547 03 Oct 08 peter 191 </tr>
1547 03 Oct 08 peter 192 <tr>
1547 03 Oct 08 peter 193 <td>Iterator type</td>
3295 25 Jul 14 peter 194 <td><tt>X::iterator</tt></td>
1547 03 Oct 08 peter 195 <td>
1547 03 Oct 08 peter 196
1547 03 Oct 08 peter 197 A mutable iterator similar to Const iterator type, which can be used to
1547 03 Oct 08 peter 198 iterate over the \ref concept_mutable_container_2d (and modify the
1547 03 Oct 08 peter 199 elements). Typically the iterator iterates along a row, and when the
1547 03 Oct 08 peter 200 end of one row is reached it jumps to the beginning of the next row.
1547 03 Oct 08 peter 201
1547 03 Oct 08 peter 202 </td>
1547 03 Oct 08 peter 203 </tr>
1547 03 Oct 08 peter 204 <tr>
1547 03 Oct 08 peter 205 <td>Column iterator type</td>
3295 25 Jul 14 peter 206 <td><tt>X::column_iterator</tt></td>
1547 03 Oct 08 peter 207 <td>
1547 03 Oct 08 peter 208 A mutable iterator that can be used to modify the elements in one
1547 03 Oct 08 peter 209 column of the \ref concept_mutable_container_2d.
1547 03 Oct 08 peter 210 </td>
1547 03 Oct 08 peter 211 </tr>
1547 03 Oct 08 peter 212 <tr>
1547 03 Oct 08 peter 213 <td>Row iterator type</td>
3295 25 Jul 14 peter 214 <td><tt>X::row_iterator</tt></td>
1547 03 Oct 08 peter 215 <td>
1547 03 Oct 08 peter 216 A mutable iterator that can be used to modify the elements in one
1547 03 Oct 08 peter 217 row of the \ref concept_mutable_container_2d.
1547 03 Oct 08 peter 218 </td>
1547 03 Oct 08 peter 219 </tr>
1547 03 Oct 08 peter 220 </table>
1547 03 Oct 08 peter 221
3295 25 Jul 14 peter 222 \subsection concept_mutable_container_2d_public_functions Public Functions
1547 03 Oct 08 peter 223
2299 12 Jul 10 peter 224 <table cellspacing=0 border=1>
1547 03 Oct 08 peter 225 <tr>
1547 03 Oct 08 peter 226 <th>Name</th><th>Expression</th><th>Precondition</th><th>Return type</th>
1547 03 Oct 08 peter 227 <th>Postcondition</th>
1547 03 Oct 08 peter 228 </tr>
1547 03 Oct 08 peter 229 <tr>
1547 03 Oct 08 peter 230 <td>Beginning of range</td>
1547 03 Oct 08 peter 231 <td><tt>a.begin()</tt></td>
1547 03 Oct 08 peter 232 <td>&nbsp;</td>
1547 03 Oct 08 peter 233 <td><tt>iterator</tt></td>
1547 03 Oct 08 peter 234 <td><tt>iterator</tt> is derefenceable, unless <tt>a</tt> is empty</td>
1547 03 Oct 08 peter 235 </tr>
1547 03 Oct 08 peter 236 <tr>
1547 03 Oct 08 peter 237 <td>Beginning of column</td>
1547 03 Oct 08 peter 238 <td><tt>a.begin_column(size_t column)</tt></td>
1547 03 Oct 08 peter 239 <td><tt>0 &lt;= column &lt; a.columns()</tt></td>
1547 03 Oct 08 peter 240 <td><tt>column_iterator</tt></td>
1547 03 Oct 08 peter 241 <td><tt>column_iterator</tt> is derefenceable, unless <tt>a</tt> is empty</td>
1547 03 Oct 08 peter 242 </tr>
1547 03 Oct 08 peter 243 <tr>
1547 03 Oct 08 peter 244 <td>Beginning of row</td>
1547 03 Oct 08 peter 245 <td><tt>a.begin_row(size_t row)</tt></td>
1547 03 Oct 08 peter 246 <td><tt>0 &lt;= row &lt; a.rows()</tt></td>
1547 03 Oct 08 peter 247 <td><tt>row_iterator</tt></td>
1547 03 Oct 08 peter 248 <td><tt>row_iterator</tt> is derefenceable, unless <tt>a</tt> is empty</td>
1547 03 Oct 08 peter 249 </tr>
1547 03 Oct 08 peter 250 <tr>
1547 03 Oct 08 peter 251 <td>End of range</td>
1547 03 Oct 08 peter 252 <td><tt>a.end()</tt></td>
1547 03 Oct 08 peter 253 <td>&nbsp;</td>
1547 03 Oct 08 peter 254 <td><tt>iterator</tt></td>
1547 03 Oct 08 peter 255 <td>&nbsp;</td>
1547 03 Oct 08 peter 256 </tr>
1547 03 Oct 08 peter 257 <tr>
1547 03 Oct 08 peter 258 <td>End of column</td>
1547 03 Oct 08 peter 259 <td><tt>a.end_column(size_t column)</tt></td>
1547 03 Oct 08 peter 260 <td><tt>column&lt;a.columns()</tt></td>
1547 03 Oct 08 peter 261 <td><tt>column_iterator</tt></td>
1547 03 Oct 08 peter 262 <td>&nbsp;</td>
1547 03 Oct 08 peter 263 </tr>
1547 03 Oct 08 peter 264 <tr>
1547 03 Oct 08 peter 265 <td>End of row</td>
1547 03 Oct 08 peter 266 <td><tt>a.end_row(size_t row)</tt></td>
1547 03 Oct 08 peter 267 <td><tt>row&lt;a.rows()</tt></td>
1547 03 Oct 08 peter 268 <td><tt>row_iterator</tt></td>
1547 03 Oct 08 peter 269 <td>&nbsp;</td>
1547 03 Oct 08 peter 270 </tr>
1547 03 Oct 08 peter 271 <tr>
1547 03 Oct 08 peter 272 <td>Element Access</td>
1547 03 Oct 08 peter 273 <td><tt>a(size_t row, size_t column)</tt></td>
3295 25 Jul 14 peter 274 <td><tt>0 &lt;= row &lt; a.rows()</tt> and
1547 03 Oct 08 peter 275 <tt>0 &lt;= column &lt; a.columns()</tt></td>
1547 03 Oct 08 peter 276 <td><tt>reference</tt></td>
1547 03 Oct 08 peter 277 <td>&nbsp;</td>
1547 03 Oct 08 peter 278 </tr>
1547 03 Oct 08 peter 279 </table>
1547 03 Oct 08 peter 280
3295 25 Jul 14 peter 281 \section concept_mutable_container_2d_implementations Implementations
1545 01 Oct 08 peter 282
1547 03 Oct 08 peter 283 Examples of concept \ref concept_mutable_container_2d include:
1547 03 Oct 08 peter 284   - theplu::yat::utility::Matrix,
1547 03 Oct 08 peter 285   - theplu::yat::utility::MatrixWeighted
1545 01 Oct 08 peter 286
1545 01 Oct 08 peter 287 */
1545 01 Oct 08 peter 288
1545 01 Oct 08 peter 289 /**
1112 21 Feb 08 markus 290 \page concept_distance Distance
1112 21 Feb 08 markus 291
3295 25 Jul 14 peter 292 \section concept_distance_description Description
1112 21 Feb 08 markus 293
1115 21 Feb 08 markus 294 \ref concept_distance is a concept for classes implementing different
3548 01 Jan 17 peter 295 alternatives to calculate the distance between two ranges. For details
3548 01 Jan 17 peter 296 on requirements needed for a class modelling the concept \ref
3548 01 Jan 17 peter 297 concept_distance refer to section below, but a convenient way to
3548 01 Jan 17 peter 298 implement a class is to use class theplu::yat::statistics::Distance as
3548 01 Jan 17 peter 299 base class.
1112 21 Feb 08 markus 300
3295 25 Jul 14 peter 301 \section concept_distance_requirments Requirements
1112 21 Feb 08 markus 302
2338 16 Oct 10 peter 303 Classes modelling the concept \ref concept_distance should have a copy
3295 25 Jul 14 peter 304 constructor
1112 21 Feb 08 markus 305
1115 21 Feb 08 markus 306 \verbatim
2338 16 Oct 10 peter 307 Distance(const Distance& d);
2338 16 Oct 10 peter 308 \endverbatim
2338 16 Oct 10 peter 309
2338 16 Oct 10 peter 310 and also implement the following public function:
2338 16 Oct 10 peter 311
2338 16 Oct 10 peter 312 \verbatim
3548 01 Jan 17 peter 313 template<typename Iterator1, typename Iterator2>
3548 01 Jan 17 peter 314 double   operator() (Iterator1 beg1, Iterator1 end1, Iterator2 beg2) const
1115 21 Feb 08 markus 315 \endverbatim
1115 21 Feb 08 markus 316
1115 21 Feb 08 markus 317 This function should calculate and return the distance between
1115 21 Feb 08 markus 318 elements of two ranges. The first range is given by [\a beg1, \a end1)
1115 21 Feb 08 markus 319 and the second range starts with \a beg2 and has the same length as
3548 01 Jan 17 peter 320 the first range. The function should support iterators that model \ref
3548 01 Jan 17 peter 321 concept_data_iterator and \forward_traversal_iterator, in other words,
3548 01 Jan 17 peter 322 the function should not assume any functionality not guaranteed by
3548 01 Jan 17 peter 323 concepts \forward_traversal_iterator and \readable_iterator.
3548 01 Jan 17 peter 324
3549 01 Jan 17 peter 325 As \ref concept_data_iterator should be supported, class
3548 01 Jan 17 peter 326 should support \ref concept_weighted_iterator. Typically a \ref
3548 01 Jan 17 peter 327 concept_distance class has a fast calculation for the case when
3548 01 Jan 17 peter 328 neither of the two input ranges is weighted, and a separate function
3548 01 Jan 17 peter 329 taking care of weights. A convenient way to select between unweighted and
3548 01 Jan 17 peter 330 weighted implementations is to utilize tag structs
3295 25 Jul 14 peter 331 theplu::yat::utility::unweighted_iterator_tag and
3548 01 Jan 17 peter 332 theplu::yat::utility::weighted_iterator_tag as returned from meta-function
3548 01 Jan 17 peter 333 theplu::yat::utility::weighted_if_any2.
1115 21 Feb 08 markus 334
3548 01 Jan 17 peter 335 The class theplu::yat::utility::DistanceConcept an be used to test
3548 01 Jan 17 peter 336 that a class fulfills these requirements.
3548 01 Jan 17 peter 337
3295 25 Jul 14 peter 338 \section concept_distance_implementations Implementations
1115 21 Feb 08 markus 339
1112 21 Feb 08 markus 340 Examples of classes modelling the concept \ref concept_distance
1112 21 Feb 08 markus 341 include theplu::yat::statistics::PearsonDistance and
1112 21 Feb 08 markus 342 theplu::yat::statistics::EuclideanDistance.
1112 21 Feb 08 markus 343
1181 27 Feb 08 peter 344 \see \ref weighted_distance
1181 27 Feb 08 peter 345
1073 12 Feb 08 markus 346 */
1112 21 Feb 08 markus 347
1112 21 Feb 08 markus 348 /**
1112 21 Feb 08 markus 349 \page concept_neighbor_weighting Neighbor Weighting Method
1112 21 Feb 08 markus 350
3295 25 Jul 14 peter 351 \section concept_neighbor_weighting_description Description
1112 21 Feb 08 markus 352
1112 21 Feb 08 markus 353 \ref concept_neighbor_weighting is a concept used in connection with
1112 21 Feb 08 markus 354 theplu::yat::classifier::KNN - classes used as the template argument
1112 21 Feb 08 markus 355 NeighborWeighting should implement this concept.
1112 21 Feb 08 markus 356
3295 25 Jul 14 peter 357 \section concept_neighbor_weighting_requirements Requirements
1112 21 Feb 08 markus 358
1112 21 Feb 08 markus 359 Classes modelling the concept \ref concept_neighbor_weighting should
3295 25 Jul 14 peter 360 be DefaultConstructible and Assignable as well as
1115 21 Feb 08 markus 361 implement the following public function:
3295 25 Jul 14 peter 362
3295 25 Jul 14 peter 363 \verbatim
3295 25 Jul 14 peter 364 void operator()(const utility::VectorBase& distance,
1522 23 Sep 08 peter 365                 const std::vector<size_t>& k_sorted,
3295 25 Jul 14 peter 366                 const Target& target,
1522 23 Sep 08 peter 367                 utility::VectorMutable& prediction) const
1112 21 Feb 08 markus 368 \endverbatim
1112 21 Feb 08 markus 369
1112 21 Feb 08 markus 370 For a test sample, this function should calculate a total vote
1112 21 Feb 08 markus 371 (i.e. based on all k nearest neighbors) for each class. The vector \a
1112 21 Feb 08 markus 372 distance contains the distances from a test sample to all training
1112 21 Feb 08 markus 373 samples. The vector \a k_sorted contains the indices (for both \a
1112 21 Feb 08 markus 374 distance and \a target) to the k training samples with the smallest
1112 21 Feb 08 markus 375 distances to the test sample. The class for each training sample is
1112 21 Feb 08 markus 376 given by \a target, which is sorted in the same sample order as \a
1112 21 Feb 08 markus 377 distance. For each class the function calculates a total vote based on
1112 21 Feb 08 markus 378 the the nearest neighbors of the test sample that belong to the
1156 26 Feb 08 markus 379 class. The total vote for each class is stored in the vector \a
1156 26 Feb 08 markus 380 prediction.  The function should be implemented such that nearest
1156 26 Feb 08 markus 381 neighbors with distance infinity do not vote.
1112 21 Feb 08 markus 382
3295 25 Jul 14 peter 383 \section concept_neighbor_weighting_implementations Implementations
1115 21 Feb 08 markus 384
1112 21 Feb 08 markus 385 Examples of classes modelling the concept \ref
1112 21 Feb 08 markus 386 concept_neighbor_weighting include
1112 21 Feb 08 markus 387 theplu::yat::classifier::KNN_Uniform,
1112 21 Feb 08 markus 388 theplu::yat::classifier::KNN_ReciprocalDistance and
1112 21 Feb 08 markus 389 theplu::yat::classifier::KNN_ReciprocalRank.
1112 21 Feb 08 markus 390
1112 21 Feb 08 markus 391 */
1590 17 Oct 08 peter 392
1590 17 Oct 08 peter 393 /**
1590 17 Oct 08 peter 394 \page concept_weighted_iterator Weighted Iterator
1590 17 Oct 08 peter 395
3295 25 Jul 14 peter 396 \section concept_weighted_iterator_description Description
1590 17 Oct 08 peter 397
1590 17 Oct 08 peter 398 Most functionality in yat come in two versions: one optimized for
1590 17 Oct 08 peter 399 speed and one weighted version allowing for missing value (see \ref
1590 17 Oct 08 peter 400 weighted_statistics). For example, weighted containers such as
1590 17 Oct 08 peter 401 theplu::yat::utility::MatrixWeighted and
1590 17 Oct 08 peter 402 theplu::yat::classifier::MatrixLookupWeighted allow an easy way to
1590 17 Oct 08 peter 403 handle missing values. Iterators that iterate over such weighted
1590 17 Oct 08 peter 404 containers are by definition \ref concept_weighted_iterator. This
1590 17 Oct 08 peter 405 concept is orthogonal against other iterator concepts such as Random
1590 17 Oct 08 peter 406 Access Iterator.
1590 17 Oct 08 peter 407
3295 25 Jul 14 peter 408 \section concept_weighted_iterator_requirements Requirements
1590 17 Oct 08 peter 409
1590 17 Oct 08 peter 410 When implementing a new iterator that may be a \ref
1590 17 Oct 08 peter 411 concept_weighted_iterator, there are a few things to concider.
1590 17 Oct 08 peter 412
1590 17 Oct 08 peter 413 \subsection weighted_iterator_traits
1590 17 Oct 08 peter 414
1590 17 Oct 08 peter 415 To decide whether an iterator is weighted, there exists a
1590 17 Oct 08 peter 416 meta-function
1590 17 Oct 08 peter 417 theplu::yat::utility::weighted_iterator_traits<Iterator>::type that
1590 17 Oct 08 peter 418 will return either theplu::yat::utility::weighted_iterator_tag or
1590 17 Oct 08 peter 419 theplu::yat::utility::unweighted_iterator_tag. The default
1590 17 Oct 08 peter 420 implementation of this meta-function works in most cases, including on
1590 17 Oct 08 peter 421 all std::iterators, but if you implement a new iterator make sure it
1590 17 Oct 08 peter 422 behaves as you desire, or you need to create a specialization.
1590 17 Oct 08 peter 423
1590 17 Oct 08 peter 424 \subsection iterator_traits
1590 17 Oct 08 peter 425
1590 17 Oct 08 peter 426 Sometimes it is useful to have unweighted iterators behaving as though
1590 17 Oct 08 peter 427 they were weighted. For instance,
1590 17 Oct 08 peter 428 theplu::yat::statistics::EuclideanDistance calculates the distance
2249 13 May 10 peter 429 between two ranges. If both ranges are unweighted the unweighted
1590 17 Oct 08 peter 430 version is used, and when any of the two ranges is weighted the
1590 17 Oct 08 peter 431 weighted version kicks in. In order to make this work also when
1590 17 Oct 08 peter 432 comparing weighted and unweighted ranges, there must a mechanism to
1590 17 Oct 08 peter 433 let the unweighted iterator behave as though it were weighted.
1590 17 Oct 08 peter 434
1590 17 Oct 08 peter 435 This can be accomplished through
1590 17 Oct 08 peter 436 theplu::yat::utility::iterator_traits, which enables access to data
1590 17 Oct 08 peter 437 value as well as to weight value. For unweighted iterators the weight
1590 17 Oct 08 peter 438 value is always equal to 1.0 and is not mutable. The default
1590 17 Oct 08 peter 439 implementation works for most iterators including all unweighted, but
1590 17 Oct 08 peter 440 if you implement a new weighted iterator you need to check that the
1590 17 Oct 08 peter 441 default implementation will work for you (see class
1590 17 Oct 08 peter 442 documentation). Otherwise, you will need to implement a
2280 26 Jun 10 peter 443 specialization. Note that the default implementation requires that, if
2312 17 Aug 10 peter 444 \c iterator is a weighted iterator, its \c reference must have
2280 26 Jun 10 peter 445 member functions data() and weight(). This should not be a problem as
2312 17 Aug 10 peter 446 long as \c reference is theplu::yat::utility::DataWeight or
2281 26 Jun 10 peter 447 theplu::yat::utility::DataWeightProxy, but could potentially be a
2312 17 Aug 10 peter 448 problem when creating weighted iterators with other \c reference.
1590 17 Oct 08 peter 449
2141 12 Jan 10 peter 450 */
2141 12 Jan 10 peter 451
2141 12 Jan 10 peter 452 /**
2141 12 Jan 10 peter 453 \page concept_data_iterator Data Iterator
2141 12 Jan 10 peter 454
3295 25 Jul 14 peter 455 \section concept_data_iterator_description Description
2141 12 Jan 10 peter 456
3295 25 Jul 14 peter 457 \ref concept_data_iterator is an iterator that is either:
2141 12 Jan 10 peter 458
2504 29 Jun 11 peter 459   - a \ref concept_weighted_iterator with value type convertible to
2504 29 Jun 11 peter 460 theplu::yat::utility::DataWeight.
2504 29 Jun 11 peter 461   - an unweighted iterator with value type convertible to \c double.
2141 12 Jan 10 peter 462
3322 06 Oct 14 peter 463 in addition
3322 06 Oct 14 peter 464
3322 06 Oct 14 peter 465   - \c theplu::yat::utility::weighted_iterator_traits<I> must work
3579 16 Jan 17 peter 466     well, which implies that iterator, \c I is a \readable_iterator
3579 16 Jan 17 peter 467     and \single_pass_iterator.
3322 06 Oct 14 peter 468
3295 25 Jul 14 peter 469 \section concept_data_iterator_implementations Implementations
2141 12 Jan 10 peter 470
2141 12 Jan 10 peter 471 Examples of concept \ref concept_data_iterator include:
2141 12 Jan 10 peter 472   - theplu::yat::utility::Matrix::iterator,
2263 26 May 10 peter 473   - theplu::yat::utility::MatrixWeighted::iterator,
2141 12 Jan 10 peter 474   - theplu::yat::classifier::MatrixLookup::const_iterator,
2141 12 Jan 10 peter 475   - theplu::yat::classifier::MatrixLookupWeighted::const_iterator
2141 12 Jan 10 peter 476 */

Generated on Sat Oct 14 02:20:18 2023 (UTC) by svndigest 0.11.2pre (dev build 1672)