Changeset 10269:a59ab9a69b0d in orange

02/17/12 00:47:49 (2 years ago)
janezd <janez.demsar@…>

Polished documentation for Orange.classification.knn

1 edited


  • docs/reference/rst/Orange.classification.knn.rst

    r10268 r10269  
    171171Orange provides classes for finding the nearest neighbors of a given 
    172 reference instance. While we might add some smarter classes in the future, we 
    173 now have only two - abstract classes that define the general behavior of 
    174 neighbor searching classes, and classes that implement brute force search. 
    176 As is the norm in Orange, there are a pair of classes: a class that does the work 
    177 (:class:`FindNearest`) and a class that constructs it ("learning" - getting the 
    178 instances and arranging them in an appropriate data structure that allows for 
    179 searching) (:class:`FindNearestConstructor`). 
     172reference instance. 
     174As usual in Orange, there are two classes: one that does the work 
     175(:class:`FindNearest`) and another that constructs the former from 
     176data (:class:`FindNearestConstructor`). 
    181178.. class:: FindNearest 
    183     A class for a brute force search for nearest neighbors. It stores a table  
    184     of instances (it's its own copy of instances, not only 
    185     with references to another When asked for neighbors, 
    186     it measures distances to all instances, stores them in a heap and returns  
    187     the first k as an with references to instances stored in 
    188     FindNearest's field instances). 
     180    Brute force search for nearest neighbors in the stored data table. 
    190182    .. attribute:: distance 
    192         a component that measures the distance between examples 
    194     .. attribute:: examples 
    196         a stored list of instances 
     184        An instance of :obj:`Orange.distance.Distance` used for 
     185        computing distances between data instances. 
     187    .. attribute:: instances 
     189        Stored data table 
    198191    .. attribute:: weight_ID 
    200         ID of meta attribute with weight 
     193        ID of meta attribute with weight. If present (non-null) the 
     194        class does not return ``k`` instances but a set of instances 
     195        with a total weight of ``k``. 
     197    .. attribute:: distance_ID 
     199        The id of meta attribute that will be added to the found 
     200        neighbours and to store the distances between the returned 
     201        data instances and the reference. If zero, the distances is 
     202        not stored. 
    202204    .. method:: __call__(instance, k) 
    204         Return a data table with ``k`` nearest neighbours of ``instance``. 
     206        Return a data table with ``k`` nearest neighbours of 
     207    ``instance``.  Any ties for the last place(s) are resolved by 
     208    randomly picking the appropriate number of instances. A local 
     209    random generator is constructed and seeded by a constant 
     210    computed from :obj:`instance`, so the same random neighbors 
     211    are always returned for the same instance. 
    206213    :param instance: given instance 
    214221.. class:: FindNearestConstructor() 
    217     A class that constructs FindNearest. It calls the inherited 
    218     distance_constructor, which constructs a distance measure. 
    219     The distance measure, along with the instances weight_ID and 
    220     distance_ID, is then passed to the just constructed instance 
    221     of FindNearest_BruteForce. 
    223     If there are more instances with the same distance fighting for the last 
    224     places, the tie is resolved by randomly picking the appropriate number of 
    225     instances. A local random generator is constructed and initiated by a 
    226     constant computed from the reference instance. The effect of this is that 
    227     the same random neighbors will be chosen for the instance each time 
    228     FindNearest_BruteForce 
    229     is called. 
     223    A class that constructs :obj:`FindNearest` and initializes it with a 
     224    distance metric, constructed by :obj:`distance_constructor`. 
    231226    .. attribute:: distance_constructor 
    233         A component of class ExamplesDistanceConstructor that "learns" to 
    234         measure distances between instances. Learning can mean, for instances, 
    235         storing the ranges of continuous features or the number of values of 
    236         a discrete feature (see the page about measuring distances for more 
    237         information). The result of learning is an instance of  
    238         ExamplesDistance that should be used for measuring distances 
    239         between instances. 
     228        An instance of :obj:`Orange.distance.DistanceConstructor` that 
     229        "learns" to measure distances between instances. Learning can 
     230        mean, for example, storing the ranges of continuous features 
     231        or the number of values of a discrete feature. The result of 
     232        learning is an instance of :obj:`Orange.distance.Distance` that is 
     233        used for measuring distances between instances. 
    241235    .. attribute:: include_same 
    243         Tells whether or not to include the examples that are same as the reference; 
    244         the default is true. 
    246     .. method:: __call__(table, weightID, distanceID) 
    248         Constructs an instance of FindNearest that would return neighbors of 
    249         a given instance, obeying weight_ID when counting them (also, some  
    250         measures of distance might consider weights as well) and storing the  
    251         distances in a meta attribute with ID distance_ID. 
     237        Indicates whether to include the instances that are same as 
     238        the reference; default is ``true``. 
     240    .. method:: __call__(data, weight_ID, distance_ID) 
     242        Constructs an instance of :obj:`FindNearest` for the given 
     243        data. Arguments :obj:`weight_ID` and :obj:`distance_ID` are copied to the new object. 
    253245        :param table: table of instances 
    254246        :type table: 
    257249        :type weight_ID: int 
    259         :param distance_ID: id of meta attribute that will save distances 
     251        :param distance_ID: id of meta attribute that will store distances 
    260252        :type distance_ID: int 
    262         :rtype: :class:`FindNearest` 
     254        :rtype: :obj:`FindNearest` 
Note: See TracChangeset for help on using the changeset viewer.