// $Id: concepts.doxygen 1487 2008-09-10 08:41:36Z jari $
//
// Copyright (C) 2008 Peter Johansson, Markus Ringnér
//
// This file is part of the yat library, http://dev.thep.lu.se/yat
//
// The yat library is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License as
// published by the Free Software Foundation; either version 3 of the
// License, or (at your option) any later version.
//
// The yat library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with yat. If not, see <http://www.gnu.org/licenses/>.


/**
\page Concepts Concepts

This page lists all the C++ concepts in the yat project.

- \subpage concept_distance
- \subpage concept_neighbor_weighting
*/


/**
\page concept_distance Distance

\section Description

\ref concept_distance is a concept for classes implementing different
alternatives to calculate the distance between two points.

\section Requirements

Classes modelling the concept \ref concept_distance should implement
the following public function:

\verbatim
template<typename Iter1, typename Iter2>
double 	operator() (Iter1 beg1, Iter1 end1, Iter2 beg2) const
\endverbatim

This function should calculate and return the distance between
elements of two ranges. The first range is given by [\a beg1, \a end1)
and the second range starts with \a beg2 and has the same length as
the first range. The function should support iterators of the category
std::forward_iterator. The function should provide both a fast
calculation for unweighted iterators and a calculation for weighted
iterators. The latter correspond to the case where elements in a range
have both a value and a weight. The selection between unweighted and
weighted implementations should utilize
theplu::yat::utility::unweighted_iterator_tag and 
theplu::yat::utility::weighted_iterator_tag. Moreover
theplu::yat::utility::weighted_if_any2 should be utilized to provide a
weighted implementation if any of the two ranges is weighted, and an
unweighted implementation when both ranges are unweighted.

\section Implementations

Examples of classes modelling the concept \ref concept_distance
include theplu::yat::statistics::PearsonDistance and
theplu::yat::statistics::EuclideanDistance.

\see \ref weighted_distance

*/

/**
\page concept_neighbor_weighting Neighbor Weighting Method

\section Description

\ref concept_neighbor_weighting is a concept used in connection with
theplu::yat::classifier::KNN - classes used as the template argument
NeighborWeighting should implement this concept.

\section Requirements

Classes modelling the concept \ref concept_neighbor_weighting should
implement the following public function:
	
\verbatim		
void operator()(const utility::VectorBase& distance, const std::vector<size_t> k_sorted,
                const Target& target, utility::VectorMutable& prediction) const
\endverbatim

For a test sample, this function should calculate a total vote
(i.e. based on all k nearest neighbors) for each class. The vector \a
distance contains the distances from a test sample to all training
samples. The vector \a k_sorted contains the indices (for both \a
distance and \a target) to the k training samples with the smallest
distances to the test sample. The class for each training sample is
given by \a target, which is sorted in the same sample order as \a
distance. For each class the function calculates a total vote based on
the the nearest neighbors of the test sample that belong to the
class. The total vote for each class is stored in the vector \a
prediction.  The function should be implemented such that nearest
neighbors with distance infinity do not vote.

\section Implementations

Examples of classes modelling the concept \ref
concept_neighbor_weighting include
theplu::yat::classifier::KNN_Uniform,
theplu::yat::classifier::KNN_ReciprocalDistance and
theplu::yat::classifier::KNN_ReciprocalRank.

*/