Ignore:
Timestamp:
02/07/12 11:20:25 (2 years ago)
Author:
markotoplak
Branch:
default
Children:
9898:dfcfd4ad5287, 9901:577a5c5e60f2, 9918:4aa830c55525
rebase_source:
c0c0acbd9d24e8688aa06cf0943beae5aded8691
Message:

Put old variable documentation Orange.feature.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • docs/reference/rst/Orange.feature.descriptor.rst

    r9896 r9897  
    1 .. automodule:: Orange.data.variable 
    2  
    3 ======================== 
    4 Variables (``variable``) 
    5 ======================== 
     1.. py:currentmodule:: Orange.feature 
     2 
     3=========================== 
     4Descriptor (``Descriptor``) 
     5=========================== 
    66 
    77Data instances in Orange can contain several types of variables: 
     
    1111The names, types, values (where applicable), functions for computing the 
    1212variable value from values of other variables, and other properties of the 
    13 variables are stored in descriptor classes derived from :obj:`Orange.data 
    14 .variable.Variable`. 
     13variables are stored in descriptor classes derived from :obj:`Descriptor`. 
    1514 
    1615Orange considers two variables (e.g. in two different data tables) the 
    1716same if they have the same descriptor. It is allowed - but not 
    18 recommended - to have different variables with the same name. 
    19  
    20 Variable descriptors 
    21 -------------------- 
    22  
    23 Variable descriptors can be constructed either by calling the 
    24 corresponding constructors or by a factory function :func:`Orange.data 
    25 .variable.make`, which either retrieves an existing descriptor or 
    26 constructs a new one. 
    27  
    28 .. class:: Variable 
     17recommended - to have different descriptors with the same name. 
     18 
     19Descriptors can be constructed either by calling the corresponding 
     20constructors or by a factory function :func:`make`, which either retrieves 
     21an existing descriptor or constructs a new one. 
     22 
     23.. class:: Descriptor 
    2924 
    3025    An abstract base class for variable descriptors. 
     
    5752 
    5853        A local random number generator used by method 
    59         :obj:`~Variable.randomvalue()`. 
     54        :obj:`~Descriptor.randomvalue()`. 
    6055 
    6156    .. attribute:: default_meta_id 
     
    9085 
    9186           Compute the value of the variable given the instance by calling 
    92            obj:`~Variable.get_value_from` through a mechanism that 
     87           obj:`~Descriptor.get_value_from` through a mechanism that 
    9388           prevents infinite recursive calls. 
    9489 
    9590           :rtype: :class:`Orange.data.Value` 
     91 
     92 
     93``Discrete`` 
     94------------ 
    9695 
    9796.. _discrete: 
    9897.. class:: Discrete 
    9998 
    100     Bases: :class:`Variable` 
     99    Bases: :class:`Descriptor` 
    101100 
    102101    Descriptor for discrete variables. 
     
    134133            this function instead of appending to ``values``. 
    135134 
     135``Continuous`` 
     136-------------- 
     137 
    136138.. _continuous: 
    137139.. class:: Continuous 
    138140 
    139     Bases: :class:`Variable` 
     141    Bases: :class:`Descriptor` 
    140142 
    141143    Descriptor for continuous variables. 
     
    182184        The range used for :obj:`randomvalue`. 
    183185 
     186``String`` 
     187---------- 
     188 
    184189.. _String: 
     190 
    185191.. class:: String 
    186192 
    187     Bases: :class:`Variable` 
     193    Bases: :class:`Descriptor` 
    188194 
    189195    Descriptor for variables that contain strings. No method can use them for 
     
    204210    string is loaded. 
    205211 
     212``Python`` 
     213---------- 
     214 
    206215.. _Python: 
    207216.. class:: Python 
    208217 
    209     Bases: :class:`Variable` 
     218    Bases: :class:`Descriptor` 
    210219 
    211220    Base class for descriptors defined in Python. It is fully functional 
     
    220229----------------------------- 
    221230 
    222 All variables have a field :obj:`~Variable.attributes`, a dictionary 
     231All variables have a field :obj:`~Descriptor.attributes`, a dictionary 
    223232that can store additional string data. 
    224233 
     
    253262The search for existing variables can end with one of the following statuses. 
    254263 
    255 .. data:: Orange.data.variable.MakeStatus.NotFound (4) 
     264.. data:: MakeStatus.NotFound (4) 
    256265 
    257266    The variable with that name and type does not exist. 
    258267 
    259 .. data:: Orange.data.variable.MakeStatus.Incompatible (3) 
     268.. data:: MakeStatus.Incompatible (3) 
    260269 
    261270    There are variables with matching name and type, but their 
     
    267276    does not matter. The formal rule is thus that the values are compatible iff ``existing_values[:len(ordered_values)] == ordered_values[:len(existing_values)]``. 
    268277 
    269 .. data:: Orange.data.variable.MakeStatus.NoRecognizedValues (2) 
     278.. data:: MakeStatus.NoRecognizedValues (2) 
    270279 
    271280    There is a matching variable, yet it has none of the values that the new 
     
    279288    some from the old. 
    280289 
    281 .. data:: Orange.data.variable.MakeStatus.MissingValues (1) 
     290.. data:: MakeStatus.MissingValues (1) 
    282291 
    283292    There is a matching variable with some of the values that the new one 
     
    286295    be values which occur in one set but not in the other. 
    287296 
    288 .. data:: Orange.data.variable.MakeStatus.OK (0) 
     297.. data:: MakeStatus.OK (0) 
    289298 
    290299    There is a perfect match which contains all the prescribed values in the 
     
    292301 
    293302Continuous variables can obviously have only two statuses, 
    294 :obj:`~Orange.data.variable.MakeStatus.NotFound` or :obj:`~Orange.data.variable.MakeStatus.OK`. 
     303:obj:`~MakeStatus.NotFound` or :obj:`~MakeStatus.OK`. 
    295304 
    296305When loading the data using :obj:`Orange.data.Table`, Orange takes the safest 
    297306approach and, by default, reuses everything that is compatible up to 
    298 and including :obj:`~Orange.data.variable.MakeStatus.NoRecognizedValues`. Unintended reuse would be obvious from the 
     307and including :obj:`~MakeStatus.NoRecognizedValues`. Unintended reuse would be obvious from the 
    299308variable having too many values, which the user can notice and fix. More on that 
    300309in the page on :doc:`Orange.data.formats`. 
     
    302311There are two functions for reusing the variables instead of creating new ones. 
    303312 
    304 .. function:: Orange.data.variable.make(name, type, ordered_values, unordered_values[, create_new_on]) 
     313.. function:: make(name, type, ordered_values, unordered_values[, create_new_on]) 
    305314 
    306315    Find and return an existing variable or create a new one if none of the existing 
     
    308317 
    309318    The optional `create_new_on` specifies the status at which a new variable is 
    310     created. The status must be at most :obj:`~Orange.data.variable.MakeStatus.Incompatible` since incompatible (or 
     319    created. The status must be at most :obj:`~MakeStatus.Incompatible` since incompatible (or 
    311320    non-existing) variables cannot be reused. If it is set lower, for instance 
    312     to :obj:`~Orange.data.variable.MakeStatus.MissingValues`, a new variable is created even if there exists 
    313     a variable which is only missing the same values. If set to :obj:`~Orange.data.variable.MakeStatus.OK`, the function 
     321    to :obj:`~MakeStatus.MissingValues`, a new variable is created even if there exists 
     322    a variable which is only missing the same values. If set to :obj:`~MakeStatus.OK`, the function 
    314323    always creates a new variable. 
    315324 
    316325    The function returns a tuple containing a variable descriptor and the 
    317326    status of the best matching variable. So, if ``create_new_on`` is set to 
    318     :obj:`~Orange.data.variable.MakeStatus.MissingValues`, and there exists a variable whose status is, say, 
    319     :obj:`~Orange.data.variable.MakeStatus.NoRecognizedValues`, a variable would be created, while the second 
    320     element of the tuple would contain :obj:`~Orange.data.variable.MakeStatus.NoRecognizedValues`. If, on the other 
     327    :obj:`~MakeStatus.MissingValues`, and there exists a variable whose status is, say, 
     328    :obj:`~MakeStatus.NoRecognizedValues`, a variable would be created, while the second 
     329    element of the tuple would contain :obj:`~MakeStatus.NoRecognizedValues`. If, on the other 
    321330    hand, there exists a variable which is perfectly OK, its descriptor is 
    322     returned and the returned status is :obj:`~Orange.data.variable.MakeStatus.OK`. The function returns no 
     331    returned and the returned status is :obj:`~MakeStatus.OK`. The function returns no 
    323332    indicator whether the returned variable is reused or not. This can be, 
    324333    however, read from the status code: if it is smaller than the specified 
     
    327336    The exception to the rule is when ``create_new_on`` is OK. In this case, the 
    328337    function does not search through the existing variables and cannot know the 
    329     status, so the returned status in this case is always :obj:`~Orange.data.variable.MakeStatus.OK`. 
    330  
    331     :param name: Variable name 
    332     :param type: Variable type 
    333     :type type: Orange.data.variable.Type 
     338    status, so the returned status in this case is always :obj:`~MakeStatus.OK`. 
     339 
     340    :param name: Descriptor name 
     341    :param type: Descriptor type 
     342    :type type: Type 
    334343    :param ordered_values: a list of ordered values 
    335344    :param unordered_values: a list of values, for which the order does not 
     
    338347        of using the new one 
    339348 
    340     :return_type: a tuple (:class:`~Orange.data.variable.Variable`, int) 
    341  
    342 .. function:: Orange.data.variable.retrieve(name, type, ordered_values, onordered_values[, create_new_on]) 
     349    :return_type: a tuple (:class:`~Descriptor`, int) 
     350 
     351.. function:: retrieve(name, type, ordered_values, onordered_values[, create_new_on]) 
    343352 
    344353    Find and return an existing variable, or :obj:`None` if no match is found. 
     
    346355    :param name: variable name. 
    347356    :param type: variable type. 
    348     :type type: Orange.data.variable.Type 
     357    :type type: Type 
    349358    :param ordered_values: a list of ordered values 
    350359    :param unordered_values: a list of values, for which the order does not 
     
    353362        of using the new one 
    354363 
    355     :return_type: :class:`~Orange.data.variable.Variable` 
     364    :return_type: :class:`~Descriptor` 
    356365 
    357366The following examples give the shown results if 
    358367executed only once (in a Python session) and in this order. 
    359368 
    360 :func:`Orange.data.variable.make` can be used for the construction of new variables. :: 
    361  
    362     >>> v1, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, ["a", "b"]) 
     369:func:`make` can be used for the construction of new variables. :: 
     370 
     371    >>> v1, s = Orange.feature.make("a", Orange.data.Type.Discrete, ["a", "b"]) 
    363372    >>> print s, v1.values 
    364373    NotFound <a, b> 
     
    367376.MakeStatus.NotFound`. :: 
    368377 
    369     >>> v2, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, ["a"], ["c"]) 
     378    >>> v2, s = Orange.feature.make("a", Orange.data.Type.Discrete, ["a"], ["c"]) 
    370379    >>> print s, v2 is v1, v1.values 
    371380    MissingValues True <a, b, c> 
    372381 
    373 The status is :obj:`~Orange.data.variable.MakeStatus.MissingValues`, 
     382The status is :obj:`~MakeStatus.MissingValues`, 
    374383yet the variable is reused (``v2 is v1``). ``v1`` gets a new value, 
    375384``"c"``, which was given as an unordered value. It does 
    376385not matter that the new variable does not need the value ``b``. :: 
    377386 
    378     >>> v3, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, ["a", "b", "c", "d"]) 
     387    >>> v3, s = Orange.feature.make("a", Orange.data.Type.Discrete, ["a", "b", "c", "d"]) 
    379388    >>> print s, v3 is v1, v1.values 
    380389    MissingValues True <a, b, c, d> 
     
    383392ordered values. :: 
    384393 
    385     >>> v4, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, ["b"]) 
     394    >>> v4, s = Orange.feature.make("a", Orange.data.Type.Discrete, ["b"]) 
    386395    >>> print s, v4 is v1, v1.values, v4.values 
    387396    Incompatible, False, <b>, <a, b, c, d> 
     
    389398The new variable needs to have ``b`` as the first value, so it is incompatible 
    390399with the existing variables. The status is 
    391 :obj:`~Orange.data.variable.MakeStatus.Incompatible` and 
     400:obj:`~MakeStatus.Incompatible` and 
    392401a new variable is created; the two variables are not equal and have 
    393402different lists of values. :: 
    394403 
    395     >>> v5, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, None, ["c", "a"]) 
     404    >>> v5, s = Orange.feature.make("a", Orange.data.Type.Discrete, None, ["c", "a"]) 
    396405    >>> print s, v5 is v1, v1.values, v5.values 
    397406    OK True <a, b, c, d> <a, b, c, d> 
    398407 
    399408The new variable has values ``c`` and ``a``, but the order is not important, 
    400 so the existing attribute is :obj:`~Orange.data.variable.MakeStatus.OK`. :: 
    401  
    402     >>> v6, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, None, ["e"]) "a"]) 
     409so the existing attribute is :obj:`~MakeStatus.OK`. :: 
     410 
     411    >>> v6, s = Orange.feature.make("a", Orange.data.Type.Discrete, None, ["e"]) "a"]) 
    403412    >>> print s, v6 is v1, v1.values, v6.values 
    404413    NoRecognizedValues True <a, b, c, d, e> <a, b, c, d, e> 
    405414 
    406415The new variable has different values than the existing variable (status 
    407 is :obj:`~Orange.data.variable.MakeStatus.NoRecognizedValues`), 
     416is :obj:`~MakeStatus.NoRecognizedValues`), 
    408417but the existing one is nonetheless reused. Note that we 
    409418gave ``e`` in the list of unordered values. If it was among the ordered, the 
    410419reuse would fail. :: 
    411420 
    412     >>> v7, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, None, 
    413             ["f"], Orange.data.variable.MakeStatus.NoRecognizedValues))) 
     421    >>> v7, s = Orange.feature.make("a", Orange.data.Type.Discrete, None, 
     422            ["f"], Orange.feature.MakeStatus.NoRecognizedValues))) 
    414423    >>> print s, v7 is v1, v1.values, v7.values 
    415424    Incompatible False <a, b, c, d, e> <f> 
     
    419428the same as before:: 
    420429 
    421     >>> v8, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, 
    422             ["a", "b", "c", "d", "e"], None, Orange.data.variable.MakeStatus.OK) 
     430    >>> v8, s = Orange.feature.make("a", Orange.data.Type.Discrete, 
     431            ["a", "b", "c", "d", "e"], None, Orange.feature.MakeStatus.OK) 
    423432    >>> print s, v8 is v1, v1.values, v8.values 
    424433    OK False <a, b, c, d, e> <a, b, c, d, e> 
Note: See TracChangeset for help on using the changeset viewer.