Changeset 10373:7013ad52894e in orange


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

Improved, simplified and updated documentation about classification.classfromvar

File:
1 edited

Legend:

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

    r10135 r10373  
    77************************ 
    88 
    9 Classifiers from variable are used not to predict class values 
    10 but to compute variable's values from another variables. 
    11 For instance, when a continuous variable is discretized and replaced by 
    12 a discrete variable, an instance of a classifier from variable takes 
    13 care of automatic value computation when needed. 
     9:obj:`~Orange.classification.ClassifierFromVar` and 
     10:obj:`~Orange.classification.ClassifierFromVarFD` are helper 
     11classifiers used to compute variable's values from another variables. They are used, for instance, in discretization of continuous variables. 
    1412 
    15 There are two classifiers from variable; the simpler :obj:`~Orange.classification.ClassifierFromVarFD` 
    16 supposes that example is from some fixed domain and the safer 
    17 :obj:`~Orange.classification.ClassifierFromVar` does not. 
     13:obj:`~Orange.classification.ClassifierFromVarFD` retrieves the 
     14feature value based on its position in the domain and 
     15:obj:`~Orange.classification.ClassifierFromVar` retrieves the feature 
     16with the given descriptor. 
    1817 
    19 Both classifiers can be given a transformer that can modify the value. 
    20 In discretization, for instance, the transformer is responsible to compute 
    21 a discrete interval for a continuous value of the original variable. 
     18Both classifiers can be given a function to transform the value. In 
     19discretization, for instance, the transformer computes the 
     20corresponding discrete interval for a continuous value of the original 
     21variable. 
    2222 
    2323 
    24 ClassifierFromVar 
    25 ================= 
    26  
    27 .. class:: ClassifierFromVar(which_var, transformer) 
     24.. class:: ClassifierFromVar(which_var[, transformer]) 
    2825     
    29     Compute variable's values from variable which_var using 
    30     transformation defined by transformer.         
    31  
     26    Return the value of variable :obj:`which_var`; transform it by the 
     27    :obj:`transformer`, if it is given. 
     28  
    3229    .. attribute:: which_var 
    3330 
    34         The descriptor of the attribute whose value is to be returned. 
     31        The descriptor of the feature whose value is returned. 
    3532 
    3633    .. attribute:: transformer         
    3734 
    38         The transformer for the value. It should be a class derived from 
    39         TransformValue, but you can also use a callback function. 
     35        The transformer for the value. It should be a class derived 
     36        from :obj:`Orange.data.utils.TransformValue` or a function 
     37        written in Python. 
     38 
     39    .. attribute:: transform_unknowns 
     40 
     41        Defines the treatment of missing values. 
    4042 
    4143    .. attribute:: distribution_for_unknown 
    4244 
    43         The distribution that is returned when the which_var's value is undefined. 
     45        The distribution that is returned when the `which_var`'s value 
     46        is undefined and :obj:`transform_unknowns` is ``False``. 
    4447 
    45 When given an instance, :obj:`~Orange.classification.ClassifierFromVar` will return 
    46 transformer(instance[which_var]). Attribute which_var can be either an ordinary variable, 
    47 a meta variable or a variable which is not defined for the instance but has getValueFrom 
    48 that can be used to compute the value. If none goes through or if the value found is unknown, 
    49 a Value of subtype Distribution containing distributionForUnknown is returned. 
     48    .. method:: __call__(inst[, result_type]) 
    5049 
    51 The class stores the domain version for the last example and its position in the domain. 
    52 If consecutive examples come from the same domain (which is usually the case), 
    53 :obj:`~Orange.classification.ClassifierFromVar` is just two simple ifs slower than  
    54 :obj:`~Orange.classification.ClassifierFromVarFD`. 
     50        Return ``transformer(instance[which_var])``. The value of 
     51        :obj:`which_var` can be either an ordinary variable, a meta 
     52        variable or a variable which is not defined for the instance 
     53        but its descriptor has a 
     54        :obj:`~Orange.feature.Descriptor.get_value_from` that can be 
     55        used to compute the value. 
    5556 
    56 As you might have guessed, the crucial component here is the transformer. 
    57 Let us, for sake of demonstration, load a Monk 1 dataset and construct an attribute 
    58 e1 that will have value "1", when e is "1", and "not 1" when e is different than 1. 
    59 There are many ways to do it, and that same problem is covered in different places 
    60 in Orange documentation. Although the way presented here is not the simplest, 
    61 it will serve to demonstrate how ClassifierFromVar works. 
     57        If the feature is not found or its value is missing, the 
     58        missing value is passed to the transformer if 
     59        :obj:`transform_unknowns` is ``True``. Otherwise, 
     60        :obj:`distribution_for_unknown` is returned. 
    6261 
     62The following example demonstrates the use of the class on the Monk 1 
     63dataset. It construct a new variable `e1` that has a value of `1`, when 
     64`e` is `1`, and `not 1` otherwise. 
    6365 
    6466.. literalinclude:: code/classifier-from-var-example.py 
    6567    :lines: 1-19 
    6668 
    67 ClassifierFromVarFD 
    68 =================== 
     69 
    6970 
    7071.. class:: ClassifierFromVarFD 
    7172 
    72     :obj:`~Orange.classification.ClassifierFromVarFD` is very similar to :obj:`~Orange.classification.ClassifierFromVar` except that the variable 
    73     is not given as a descriptor (like which_var) but as an index. The index can be 
    74     either a position of the variable in the domain or a meta-id. Given that :obj:`~Orange.classification.ClassifierFromVarFD` 
    75     is practically no faster than :obj:`~Orange.classification.ClassifierFromVar` (and can in future even be merged with the latter), 
    76     you should seldom need to use the class. 
     73    A class similar to 
     74    :obj:`~Orange.classification.ClassifierFromVar` except that the 
     75    variable is given by its index in the domain. The index can also 
     76    be negative to denote a meta attribute. 
     77 
     78    The only practical difference between the two classes is that this 
     79    does not compute the value of the variable from other variables 
     80    through the descriptor's 
     81    :obj:`Orange.feature.Descriptor.get_value_from`. 
    7782 
    7883    .. attribute:: domain (inherited from ClassifierFromVarFD) 
    7984     
    80         The domain on which the classifier operates. 
     85        The domain to which the :obj:`position` applies. 
    8186 
    8287    .. attribute:: position 
     
    8489        The position of the attribute in the domain or its meta-id. 
    8590 
    86     .. attribute:: transformer 
     91    .. attribute:: transformer         
    8792 
    88         The transformer for the value. 
     93        The transformer for the value. It should be a class derived 
     94        from :obj:`Orange.data.utils.TransformValue` or a function 
     95        written in Python. 
     96 
     97    .. attribute:: transform_unknowns 
     98 
     99        Defines the treatment of missing values. 
    89100 
    90101    .. attribute:: distribution_for_unknown 
    91102 
    92         The distribution that is returned when the which_var's value is undefined. 
     103        The distribution that is returned when the `which_var`'s value 
     104        is undefined and :obj:`transform_unknowns` is ``False``. 
    93105 
    94 When an example is passed to :obj:`~Orange.classification.ClassifierFromVarFD`, 
    95 it is first checked whether it is 
    96 from the correct domain; an exception is raised if not. If the domain is OK, 
    97 the corresponding attribute value is retrieved, transformed and returned. 
     106    The use of this class is similar to that of  
     107    :obj:`~Orange.classification.ClassifierFromVar`. 
    98108 
    99 :obj:`~Orange.classification.ClassifierFromVarFD`'s twin brother, :obj:`~Orange.classification.ClassifierFromVar`, can also handle variables that 
    100 are not in the instances' domain or meta-variables, but can be computed therefrom by using 
    101 their getValueFrom. Since :obj:`~Orange.classification.ClassifierFromVarFD` doesn't store attribute descriptor but 
    102 only an index, such functionality is obviously impossible. 
    103  
    104 To rewrite the above script to use :obj:`~Orange.classification.ClassifierFromVarFD`, 
    105 we need to set the domain and the e's index to position 
    106 (equivalent to setting which_var in :obj:`~Orange.classification.ClassifierFromVar`). 
    107 The initialization of :obj:`~Orange.classification.ClassifierFromVarFD` thus goes like this: 
    108  
    109 .. literalinclude:: code/classifier-from-var-example.py 
    110     :lines: 21-25 
     109    .. literalinclude:: code/classifier-from-var-example.py 
     110        :lines: 21-25 
Note: See TracChangeset for help on using the changeset viewer.