Changeset 10269:a59ab9a69b0d in orange


Ignore:
Timestamp:
02/17/12 00:47:49 (2 years ago)
Author:
janezd <janez.demsar@…>
Branch:
default
Message:

Polished documentation for Orange.classification.knn

File:
1 edited

Legend:

Unmodified
Added
Removed
  • docs/reference/rst/Orange.classification.knn.rst

    r10268 r10269  
    170170 
    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. 
    175  
    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. 
     173 
     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`). 
    180177 
    181178.. class:: FindNearest 
    182179 
    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 Orange.data.Table 
    185     with references to another Orange.data.Table). When asked for neighbors, 
    186     it measures distances to all instances, stores them in a heap and returns  
    187     the first k as an Orange.data.Table with references to instances stored in 
    188     FindNearest's field instances). 
     180    Brute force search for nearest neighbors in the stored data table. 
    189181     
    190182    .. attribute:: distance 
    191183     
    192         a component that measures the distance between examples 
    193      
    194     .. attribute:: examples 
    195      
    196         a stored list of instances 
     184        An instance of :obj:`Orange.distance.Distance` used for 
     185        computing distances between data instances. 
     186     
     187    .. attribute:: instances 
     188     
     189        Stored data table 
    197190     
    198191    .. attribute:: weight_ID 
    199192     
    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``. 
     196 
     197    .. attribute:: distance_ID 
     198 
     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. 
    201203     
    202204    .. method:: __call__(instance, k) 
    203205     
    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. 
    205212 
    206213    :param instance: given instance 
     
    214221.. class:: FindNearestConstructor() 
    215222 
    216      
    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. 
    222  
    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`. 
    230225     
    231226    .. attribute:: distance_constructor 
    232227     
    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. 
    240234     
    241235    .. attribute:: include_same 
    242236     
    243         Tells whether or not to include the examples that are same as the reference; 
    244         the default is true. 
    245      
    246     .. method:: __call__(table, weightID, distanceID) 
    247      
    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. 
    252      
     237        Indicates whether to include the instances that are same as 
     238        the reference; default is ``true``. 
     239     
     240    .. method:: __call__(data, weight_ID, distance_ID) 
     241     
     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. 
     244 
    253245        :param table: table of instances 
    254246        :type table: Orange.data.Table 
     
    257249        :type weight_ID: int 
    258250         
    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 
    261253         
    262         :rtype: :class:`FindNearest` 
     254        :rtype: :obj:`FindNearest` 
    263255 
    264256Examples 
Note: See TracChangeset for help on using the changeset viewer.