=======
neartag
=======

This module implements the k-nearest neighbor algorithme (k-NN) that allows
to compute the distance between elements, given a set of value. Each value
is a dimension and the set are the coordinates of the element in the multi
dimensional space.

For tags, the idea is to find neighbours of a given user, depending on the
tags she uses. The `NearestByTag` class is instanciated with those tags::

    >>> from neartag import NearestByTag
    >>> tags = ["django", "python", "zen", "fun", "scary"]
    >>> solver = NearestByTag(tags)

Then each user is added with her name and tag values (boolean value)::

    >>> user_1 = 'user 1', ["django", "python"]
    >>> user_2 = 'user 2', ["zen", "fun", "scary"]
    >>> user_3 = 'user 3', ["django"]
    >>> user_4 = 'user 4', ["django", "python"]
    >>> for user, tags in (user_1, user_2, user_3, user_4):
    ...     solver.add_user(user, tags)

The class then will give a sorted list of neighbours of a given user::

    >>> solver.neighbours('user 1')
    [(0.16..., 'user 4'), (0.3..., 'user 3'), (1.0, 'user 2')]
    >>> solver.neighbours('user 2')
    [(0.83..., 'user 3'), (1.0, 'user 1'), (1.0, 'user 4')]
    >>> solver.neighbours('user 3')
    [(0.33..., 'user 1'), (0.33..., 'user 4'), (0.83..., 'user 2')]
    >>> solver.neighbours('user 4')
    [(0.16..., 'user 1'), (0.33..., 'user 3'), (1.0, 'user 2')]

The smallest the returned value is, the closest the user is.

`neighbours` will return at most 10 neighbours, but this size can be changed::

    >>> solver.neighbours('user 1', 1)
    [(0.16..., 'user 4')]

This class works in-memory, since the loaded values are small enough to fit.

How to use it with an application
=================================

Tags changes all the time in an application. The best use is to instanciate
the class over data retrieved from a database and to compute the distances,
then to save them within a dedicated table. Since the computation can take
time, a thread worker can update those distances from time to time in the
background.