Changeset 7533:89be2d82aaae in orange


Ignore:
Timestamp:
02/04/11 21:12:44 (3 years ago)
Author:
lanz <lan.zagar@…>
Branch:
default
Convert:
ed73c1b190e3d7320e30f8316a7c0d5cf0f54c33
Message:

Documentation changes.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • orange/Orange/classification/lookup.py

    r7404 r7533  
    5353    e2.getValueFrom = lambda ex, rw: orange.Value(e2, ex["e"]=="1") 
    5454 
     55 
    5556=========================== 
    5657Classifiers by Lookup Table 
     
    5859 
    5960Although the above example used :obj:`ClassifierByLookupTable` as if it 
    60 was a concrete class, :obj:`ClassifierByLookupTable` is actually 
     61was a concrete class, ClassifierByLookupTable is actually 
    6162abstract. Calling its constructor is a typical Orange trick: what you 
    62 get, is never :obj:`ClassifierByLookupTable`, but either 
     63get, is never ClassifierByLookupTable, but either 
    6364:obj:`ClassifierByLookupTable1`, :obj:`ClassifierByLookupTable2` or 
    6465:obj:`ClassifierByLookupTable3`. As their names tell, the first 
     
    7677constructed. 
    7778 
    78 **Attributes:** 
    79  
    80 .. attribute:: variable1[, variable2[, variable3]](read only) 
    81      
    82     The feature(s) that the classifier uses for classification. 
    83     ClassifierByLookupTable1 only has variable1, 
    84     ClassifierByLookupTable2 also has variable2 and 
    85     ClassifierByLookupTable3 has all three. 
    86  
    87 .. attribute:: variables (read only) 
    88      
    89     The above variables, returned as a tuple. 
    90  
    91 .. attribute:: noOfValues1, noOfValues2[, noOfValues3] (read only) 
    92      
    93     The number of values for variable1, variable2 and variable3. 
    94     This is stored here to make the classifier faster. Those features 
    95     are defined only for ClassifierByLookupTable2 (the first two) and 
    96     ClassifierByLookupTable3 (all three). 
    97  
    98 .. attribute:: lookupTable (read only) 
    99      
    100     A list of values (ValueList), one for each possible combination of 
    101     features. For ClassifierByLookupTable1, there is an additional 
    102     element that is returned when the feature's value is unknown. 
    103     Values are ordered by values of features, with variable1 being the 
    104     most important. In case of two three valued features, the list 
    105     order is therefore 1-1, 1-2, 1-3, 2-1, 2-2, 2-3, 3-1, 3-2, 3-3, 
    106     where the first digit corresponds to variable1 and the second to 
    107     variable2. 
    108      
    109     The list is read-only in the sense that you cannot assign a new 
    110     list to this field. You can, however, change its elements. Don't 
    111     change its size, though.  
    112  
    113 .. attribute:: distributions (read only) 
    114      
    115     Similar to :obj:`lookupTable`, but is of type DistributionList 
    116     and stores a distribution for each combination of values.  
    117  
    118 .. attribute:: dataDescription 
    119      
    120     An object of type EFMDataDescription, defined only for 
    121     ClassifierByLookupTable2 and ClassifierByLookupTable3. They use 
    122     it to make predictions when one or more feature values are unknown. 
    123     ClassifierByLookupTable1 doesn't need it since this case is covered 
    124     by an additional element in lookupTable and distributions, 
    125     as told above.  
    126  
    127 **Methods:** 
    128  
    129 .. method:: ClassifierByLookupTable(classVar, variable1[, variable2[, variable3]] [, lookupTable[, distributions]]) 
    130  
     79 
     80.. py:class:: Orange.classification.lookup.ClassifierByLookupTable(classVar, variable1[, variable2[, variable3]] [, lookupTable[, distributions]]) 
     81     
    13182    A general constructor that, based on the number of attribute 
    13283    descriptors, constructs one of the three classes discussed. 
     
    13586    right sizes, but their elements are don't knows and empty 
    13687    distributions. If they are given, they must be of correct size. 
    137  
    138 .. method:: ClassifierByLookupTable1(classVar, variable1 [, lookupTable, distributions]) 
    139             ClassifierByLookupTable2(classVar, variable1, variable2, [, lookupTable[, distributions]]) 
    140             ClassifierByLookupTable3(classVar, variable1, variable2, variable3, [, lookupTable[, distributions]]) 
    141      
    142     Class-specific constructors that you can call instead of the general constructor. The number of attributes must match the constructor called. 
    143  
    144 .. method:: getindex(example) 
    145      
    146     Returns an index into lookupTable or distributions. The formula 
    147     depends upon the type of the classifier. If value *i* is 
    148     int(example[variable*i*]), then the corresponding formulae are 
    149  
    150     ClassifierByLookupTable1: 
    151         index = value1, or len(lookupTable)-1 if value is unknown 
    152     ClassifierByLookupTable2: 
    153         index = value1*noOfValues1 + value2, or -1 if any value is unknown  
    154     ClassifierByLookupTable3: 
    155         index = (value1*noOfValues1 + value2) * noOfValues2 + value3, or -1 if any value is unknown 
    156  
    157     Let's see some indices for randomly chosen examples from the original table. 
    158      
    159     part of `lookup-lookup.py`_ (uses: `monks-1.tab`_): 
    160  
    161     .. literalinclude:: code/lookup-lookup.py 
    162         :lines: 26-29 
    163      
    164     Output:: 
    165      
    166         ['1', '1', '2', '2', '4', '1', '1']: ab 0, e1 3 
    167         ['3', '3', '1', '2', '2', '1', '1']: ab 8, e1 1 
    168         ['2', '1', '2', '3', '4', '2', '0']: ab 3, e1 3 
    169         ['2', '1', '1', '2', '1', '1', '1']: ab 3, e1 0 
    170         ['1', '1', '1', '2', '3', '1', '1']: ab 0, e1 2  
     88     
     89    .. attribute:: variable1[, variable2[, variable3]](read only) 
     90         
     91        The feature(s) that the classifier uses for classification. 
     92        ClassifierByLookupTable1 only has variable1, 
     93        ClassifierByLookupTable2 also has variable2 and 
     94        ClassifierByLookupTable3 has all three. 
     95 
     96    .. attribute:: variables (read only) 
     97         
     98        The above variables, returned as a tuple. 
     99 
     100    .. attribute:: noOfValues1, noOfValues2[, noOfValues3] (read only) 
     101         
     102        The number of values for variable1, variable2 and variable3. 
     103        This is stored here to make the classifier faster. Those features 
     104        are defined only for ClassifierByLookupTable2 (the first two) and 
     105        ClassifierByLookupTable3 (all three). 
     106 
     107    .. attribute:: lookupTable (read only) 
     108         
     109        A list of values (ValueList), one for each possible combination of 
     110        features. For ClassifierByLookupTable1, there is an additional 
     111        element that is returned when the feature's value is unknown. 
     112        Values are ordered by values of features, with variable1 being the 
     113        most important. In case of two three valued features, the list 
     114        order is therefore 1-1, 1-2, 1-3, 2-1, 2-2, 2-3, 3-1, 3-2, 3-3, 
     115        where the first digit corresponds to variable1 and the second to 
     116        variable2. 
     117         
     118        The list is read-only in the sense that you cannot assign a new 
     119        list to this field. You can, however, change its elements. Don't 
     120        change its size, though.  
     121 
     122    .. attribute:: distributions (read only) 
     123         
     124        Similar to :obj:`lookupTable`, but is of type DistributionList 
     125        and stores a distribution for each combination of values.  
     126 
     127    .. attribute:: dataDescription 
     128         
     129        An object of type EFMDataDescription, defined only for 
     130        ClassifierByLookupTable2 and ClassifierByLookupTable3. They use 
     131        it to make predictions when one or more feature values are unknown. 
     132        ClassifierByLookupTable1 doesn't need it since this case is covered 
     133        by an additional element in lookupTable and distributions, 
     134        as told above. 
     135         
     136    .. method:: getindex(example) 
     137     
     138        Returns an index into lookupTable or distributions. The formula 
     139        depends upon the type of the classifier. If value\ *i* is 
     140        int(example[variable\ *i*]), then the corresponding formulae are 
     141 
     142        ClassifierByLookupTable1: 
     143            index = value1, or len(lookupTable)-1 if value is unknown 
     144        ClassifierByLookupTable2: 
     145            index = value1*noOfValues1 + value2, or -1 if any value is unknown  
     146        ClassifierByLookupTable3: 
     147            index = (value1*noOfValues1 + value2) * noOfValues2 + value3, or -1 if any value is unknown 
     148 
     149        Let's see some indices for randomly chosen examples from the original table. 
     150         
     151        part of `lookup-lookup.py`_ (uses: `monks-1.tab`_): 
     152 
     153        .. literalinclude:: code/lookup-lookup.py 
     154            :lines: 26-29 
     155         
     156        Output:: 
     157         
     158            ['1', '1', '2', '2', '4', '1', '1']: ab 0, e1 3 
     159            ['3', '3', '1', '2', '2', '1', '1']: ab 8, e1 1 
     160            ['2', '1', '2', '3', '4', '2', '0']: ab 3, e1 3 
     161            ['2', '1', '1', '2', '1', '1', '1']: ab 3, e1 0 
     162            ['1', '1', '1', '2', '3', '1', '1']: ab 0, e1 2  
     163 
     164 
     165 
     166.. py:class:: Orange.classification.lookup.ClassifierByLookupTable1(classVar, variable1 [, lookupTable, distributions]) 
     167     
     168    Uses a single feature for lookup. See 
     169    :obj:`ClassifierByLookupTable` for more details. 
     170 
     171.. py:class:: Orange.classification.lookup.ClassifierByLookupTable2(classVar, variable1, variable2, [, lookupTable[, distributions]]) 
     172     
     173    Uses two features for lookup. See 
     174    :obj:`ClassifierByLookupTable` for more details. 
     175         
     176.. py:class:: Orange.classification.lookup.ClassifierByLookupTable3(classVar, variable1, variable2, variable3, [, lookupTable[, distributions]]) 
     177     
     178    Uses three features for lookup. See 
     179    :obj:`ClassifierByLookupTable` for more details. 
    171180 
    172181 
     
    175184========================== 
    176185 
    177 :obj:`ClassifierByExampleTable` is the alternative to 
    178 :obj:`ClassifierByLookupTable`. It is to be used when the 
    179 classification is based on more than three features. Instead of having 
    180 a lookup table, it stores an :obj:`Orange.data.Table`, which is 
    181 optimized for a faster access. 
    182  
    183 This class is used in similar contexts as 
     186:obj:`ClassifierByExampleTable` is used in similar contexts as 
    184187:obj:`ClassifierByLookupTable`. If you write, for instance, a 
    185188constructive induction algorithm, it is recommendable that the values 
    186189of the new feature are computed either by one of classifiers by lookup 
    187 table or by :obj:`ClassifierByExampleTable`, depending on the number 
    188 of bound features. 
    189  
    190 **Attributes:** 
    191  
    192 .. attribute:: sortedExamples 
    193      
    194     A :obj:`Orange.data.Table` with sorted instances for lookup. 
    195     Instances in the table can be merged; if there were multiple 
    196     instances with the same feature values (but possibly different 
    197     classes), they are merged into a single instance. Regardless of 
    198     merging, class values in this table are distributed: their svalue 
    199     contains a :obj:`Distribution`. 
    200  
    201 .. attribute:: classifierForUnknown 
    202      
    203     This classifier is used to classify instances which were not found 
    204     in the table. If classifierForUnknown is not set, don't know's are 
    205     returned. 
    206  
    207 .. attribute:: variables (read only) 
    208      
    209     A tuple with features in the domain. This field is here so that 
    210     :obj:`ClassifierByExampleTable` appears more similar to 
    211     :obj:`ClassifierByLookupTable`. If a constructive induction 
    212     algorithm returns the result in one of these classifiers, and you 
    213     would like to check which features are used, you can use variables 
    214     regardless of the class you actually got. 
    215  
    216 There are no specific methods for :obj:`ClassifierByExampleTable`. 
    217 Since this is a classifier, it can be called. When the instance to be 
    218 classified includes unknown values, :obj:`classifierForUnknown` will be 
    219 used if it is defined. 
    220  
    221 Although :obj:`ClassifierByExampleTable` is not really a classifier in 
    222 the sense that you will use it to classify instances, but is rather a 
    223 function for computation of intermediate values, it has an associated 
    224 learner, :obj:`LookupLearner`. The learner's task is, basically, to 
    225 construct a Table for :obj:`sortedExamples`. It sorts them, merges them 
    226 and, of course, regards instance weights in the process as well. 
     190table or by ClassifierByExampleTable, depending on the number of bound 
     191features. 
     192 
     193.. py:class:: Orange.classification.lookup.ClassifierByExampleTable() 
     194 
     195    :obj:`ClassifierByExampleTable` is the alternative to 
     196    :obj:`ClassifierByLookupTable`. It is to be used when the 
     197    classification is based on more than three features. Instead of having 
     198    a lookup table, it stores an :obj:`Orange.data.Table`, which is 
     199    optimized for a faster access. 
     200     
     201 
     202    .. attribute:: sortedExamples 
     203         
     204        A :obj:`Orange.data.Table` with sorted data instances for lookup. 
     205        Instances in the table can be merged; if there were multiple 
     206        instances with the same feature values (but possibly different 
     207        classes), they are merged into a single instance. Regardless of 
     208        merging, class values in this table are distributed: their svalue 
     209        contains a :obj:`Distribution`. 
     210 
     211    .. attribute:: classifierForUnknown 
     212         
     213        This classifier is used to classify instances which were not found 
     214        in the table. If classifierForUnknown is not set, don't know's are 
     215        returned. 
     216 
     217    .. attribute:: variables (read only) 
     218         
     219        A tuple with features in the domain. This field is here so that 
     220        :obj:`ClassifierByExampleTable` appears more similar to 
     221        :obj:`ClassifierByLookupTable`. If a constructive induction 
     222        algorithm returns the result in one of these classifiers, and you 
     223        would like to check which features are used, you can use variables 
     224        regardless of the class you actually got. 
     225 
     226    There are no specific methods for ClassifierByExampleTable. 
     227    Since this is a classifier, it can be called. When the instance to be 
     228    classified includes unknown values, :obj:`classifierForUnknown` will be 
     229    used if it is defined. 
     230 
     231 
     232 
     233.. py:class:: Orange.classification.lookup.LookupLearner() 
     234     
     235    Although :obj:`ClassifierByExampleTable` is not really a classifier in 
     236    the sense that you will use it to classify instances, but is rather a 
     237    function for computation of intermediate values, it has an associated 
     238    learner, :obj:`LookupLearner`. The learner's task is, basically, to 
     239    construct a Table for :obj:`sortedExamples`. It sorts them, merges them 
     240    and, of course, regards instance weights in the process as well. 
     241     
     242    If data instances are provided to the constructor, the learning algorithm 
     243    is called and the resulting classifier is returned instead of the learner. 
    227244 
    228245part of `lookup-table.py`_ (uses: `monks-1.tab`_): 
     
    348365 
    349366 
    350 import orngMisc 
    351  
    352  
    353367def lookupFromBound(attribute, bound): 
    354368    if not len(bound): 
     
    370384    if lookup: 
    371385        lookup.lookupTable = [Orange.data.Value(attribute, function(attributes)) 
    372                               for attributes in orngMisc.LimitedCounter( 
     386                              for attributes in Orange.misc.counters.LimitedCounter( 
    373387                                  [len(attr.values) for attr in bound])] 
    374388        return lookup 
    375389    else: 
    376390        examples = Orange.data.Table(Orange.data.Domain(bound, attribute)) 
    377         for attributes in orngMisc.LimitedCounter([len(attr.values) 
     391        for attributes in Orange.misc.counters.LimitedCounter([len(attr.values) 
    378392                                                   for attr in dom.attributes]): 
    379393            examples.append(Orange.data.Example(dom, attributes + 
     
    382396       
    383397 
    384 def lookupFromExamples(examples, weight = 0, learnerForUnknown = None): 
     398def lookupFromData(examples, weight = 0, learnerForUnknown = None): 
    385399    if len(examples.domain.attributes) <= 3: 
    386400        lookup = lookupFromBound(examples.domain.classVar, 
     
    427441        lc = 0 
    428442        if len(boundset)==1: 
    429             cnt = orngMisc.LimitedCounter([len(x.values)+1 for x in boundset]) 
     443            cnt = Orange.misc.counters.LimitedCounter([len(x.values)+1 for x in boundset]) 
    430444        else: 
    431             cnt = orngMisc.LimitedCounter([len(x.values) for x in boundset]) 
     445            cnt = Orange.misc.counters.LimitedCounter([len(x.values) for x in boundset]) 
    432446        for ex in cnt: 
    433447            for i in range(len(ex)): 
Note: See TracChangeset for help on using the changeset viewer.