Changeset 8912:91f7f68707e8 in orange


Ignore:
Timestamp:
09/05/11 20:32:12 (3 years ago)
Author:
markotoplak
Branch:
default
Convert:
b06893e461c43c2f7513825288ddd398c5e14490
Message:

Orange.data.variable: added links to documentation.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • orange/Orange/data/variable.py

    r8909 r8912  
    9393 
    9494           Compute the value of the variable given the instance by calling 
    95            `get_value_from` through a mechanism that prevents deadlocks by 
     95           obj:`~Variable.get_value_from` through a mechanism that prevents deadlocks by 
    9696           circular calls. 
    9797 
     
    153153     
    154154        If ``True``, the value is printed in scientific format whenever it 
    155         would have more than 5 digits. In this case, `number_of_decimals` is 
     155        would have more than 5 digits. In this case, :obj:`number_of_decimals` is 
    156156        ignored. 
    157157 
     
    170170        be printed with the same number of decimals as the largest number of  
    171171        decimals encountered in the file. If scientific notation occurs in the  
    172         file, `scientific_format` will be set to ``True`` and scientific format  
     172        file, :obj:`scientific_format` will be set to ``True`` and scientific format  
    173173        will be used for values too large or too small.  
    174174     
     
    176176        decimal places. This can be changed either by setting the value 
    177177        from a string (e.g. ``inst[0]="3.14"``, but not ``inst[0]=3.14``) or by 
    178         manually setting the `number_of_decimals`. 
     178        manually setting the :obj:`number_of_decimals`. 
    179179 
    180180    .. attribute:: start_value, end_value, step_value 
     
    198198    When converting strings into values and back, empty strings are treated  
    199199    differently than usual. For other types, an empty string can be used to 
    200     denote undefined values, while :obj:`StringVariable` will take empty strings 
     200    denote undefined values, while :obj:`String` will take empty strings 
    201201    as empty strings -- except when loading or saving into file. 
    202202    Empty strings in files are interpreted as undefined; to specify an empty 
     
    307307The search for existing variables can end with one of the following statuses. 
    308308 
    309 Orange.data.variable.Variable.MakeStatus.NotFound (4) 
    310     The variable with that name and type does not exist. 
    311  
    312 Orange.data.variable.Variable.MakeStatus.Incompatible (3) 
     309.. data:: Orange.data.variable.MakeStatus.NotFound (4) 
     310 
     311    The variable with that name and type does not exist.  
     312 
     313.. data:: Orange.data.variable.MakeStatus.Incompatible (3) 
     314 
    313315    There are variables with matching name and type, but their 
    314316    values are incompatible with the prescribed ordered values. For example, 
     
    319321    does not matter. The formal rule is thus that the values are compatible iff ``existing_values[:len(ordered_values)] == ordered_values[:len(existing_values)]``. 
    320322 
    321 Orange.data.variable.Variable.MakeStatus.NoRecognizedValues (2) 
     323.. data:: Orange.data.variable.MakeStatus.NoRecognizedValues (2) 
     324 
    322325    There is a matching variable, yet it has none of the values that the new 
    323     variable will have (this is obviously possible only if the new attribute has 
     326    variable will have (this is obviously possible only if the new variable has 
    324327    no prescribed ordered values). For instance, we search for a variable 
    325328    "sex" with values "male" and "female", while there is a variable of the same  
     
    330333    some from the old. 
    331334 
    332 Orange.data.variable.Variable.MakeStatus.MissingValues (1) 
     335.. data:: Orange.data.variable.MakeStatus.MissingValues (1) 
     336 
    333337    There is a matching variable with some of the values that the new one  
    334338    requires, but some values are missing. This situation is neither uncommon  
     
    336340    be values which occur in one set but not in the other. 
    337341 
    338 Orange.data.variable.Variable.MakeStatus.OK (0) 
     342.. data:: Orange.data.variable.MakeStatus.OK (0) 
     343 
    339344    There is a perfect match which contains all the prescribed values in the 
    340     correct order. The existing attribute may have some extra values, though. 
    341  
    342 Continuous attributes can obviously have only two statuses, ``NotFound`` or 
    343 ``OK``. 
     345    correct order. The existing variable may have some extra values, though. 
     346 
     347Continuous variables can obviously have only two statuses,  
     348:obj:`~Orange.data.variable.MakeStatus.NotFound` or :obj:`~Orange.data.variable.MakeStatus.OK`. 
    344349 
    345350When loading the data using :obj:`Orange.data.Table`, Orange takes the safest  
    346351approach and, by default, reuses everything that is compatible up to  
    347 and including ``NoRecognizedValues``. Unintended reuse would be obvious from the 
     352and including :obj:`~Orange.data.variable.MakeStatus.NoRecognizedValues`. Unintended reuse would be obvious from the 
    348353variable having too many values, which the user can notice and fix. More on that  
    349354in the page on `loading data`. !!TODO!! 
    350355 
    351 There are two functions for reusing the attributes instead of creating new ones. 
     356There are two functions for reusing the variables instead of creating new ones. 
    352357 
    353358.. function:: Orange.data.variable.make(name, type, ordered_values, unordered_values[, create_new_on]) 
     
    357362     
    358363    The optional `create_new_on` specifies the status at which a new variable is 
    359     created. The status must be at most ``Incompatible`` since incompatible (or 
     364    created. The status must be at most :obj:`~Orange.data.variable.MakeStatus.Incompatible` since incompatible (or 
    360365    non-existing) variables cannot be reused. If it is set lower, for instance  
    361     to ``MissingValues``, a new variable is created even if there exists 
    362     a variable which is only missing the same values. If set to ``OK``, the function 
     366    to :obj:`~Orange.data.variable.MakeStatus.MissingValues`, a new variable is created even if there exists 
     367    a variable which is only missing the same values. If set to :obj:`~Orange.data.variable.MakeStatus.OK`, the function 
    363368    always creates a new variable. 
    364369     
    365370    The function returns a tuple containing a variable descriptor and the 
    366371    status of the best matching variable. So, if ``create_new_on`` is set to 
    367     ``MissingValues``, and there exists a variable whose status is, say, 
    368     ``UnrecognizedValues``, a variable would be created, while the second  
    369     element of the tuple would contain ``UnrecognizedValues``. If, on the other 
     372    :obj:`~Orange.data.variable.MakeStatus.MissingValues`, and there exists a variable whose status is, say, 
     373    :obj:`~Orange.data.variable.MakeStatus.NoRecognizedValues`, a variable would be created, while the second  
     374    element of the tuple would contain :obj:`~Orange.data.variable.MakeStatus.NoRecognizedValues`. If, on the other 
    370375    hand, there exists a variable which is perfectly OK, its descriptor is  
    371     returned and the returned status is ``OK``. The function returns no  
     376    returned and the returned status is :obj:`~Orange.data.variable.MakeStatus.OK`. The function returns no  
    372377    indicator whether the returned variable is reused or not. This can be, 
    373378    however, read from the status code: if it is smaller than the specified 
     
    375380 
    376381    The exception to the rule is when ``create_new_on`` is OK. In this case, the  
    377     function does not search through the existing attributes and cannot know the  
    378     status, so the returned status in this case is always ``OK``. 
     382    function does not search through the existing variables and cannot know the  
     383    status, so the returned status in this case is always :obj:`~Orange.data.variable.MakeStatus.OK`. 
    379384 
    380385    :param name: Variable name 
     
    415420    4 <a, b> 
    416421 
    417 No surprises here: a new variable is created and the status is ``NotFound``. :: 
     422No surprises here: a new variable is created and the status is :obj:`~Orange.data.variable.MakeStatus.NotFound`. :: 
    418423 
    419424    >>> v2, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, ["a"], ["c"]) 
     
    421426    1 True <a, b, c> 
    422427 
    423 The status is 1 (``MissingValues``), yet the variable is reused (``v2 is v1``). 
     428The status is 1 (:obj:`~Orange.data.variable.MakeStatus.MissingValues`), yet the variable is reused (``v2 is v1``). 
    424429``v1`` gets a new value, ``"c"``, which was given as an unordered value. It does 
    425430not matter that the new variable does not need the value ``b``. :: 
     
    437442 
    438443The new variable needs to have ``b`` as the first value, so it is incompatible  
    439 with the existing variables. The status is thus 3 (``Incompatible``), the two  
     444with the existing variables. The status is thus 3 (:obj:`~Orange.data.variable.MakeStatus.Incompatible`), the two  
    440445variables are not equal and have different lists of values. :: 
    441446 
     
    445450 
    446451The new variable has values ``c`` and ``a``, but the order is not important,  
    447 so the existing attribute is ``OK``. :: 
     452so the existing attribute is :obj:`~Orange.data.variable.MakeStatus.OK`. :: 
    448453 
    449454    >>> v6, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, None, ["e"]) "a"]) 
     
    452457 
    453458The new variable has different values than the existing variable (status is 2, 
    454 ``NoRecognizedValues``), but the existing one is nonetheless reused. Note that we 
     459:obj:`~Orange.data.variable.MakeStatus.NoRecognizedValues`), but the existing one is nonetheless reused. Note that we 
    455460gave ``e`` in the list of unordered values. If it was among the ordered, the 
    456461reuse would fail. :: 
    457462 
    458463    >>> v7, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, None, 
    459             ["f"], Orange.data.variable.make.MakeStatus.NoRecognizedValues))) 
     464            ["f"], Orange.data.variable.MakeStatus.NoRecognizedValues))) 
    460465    >>> print s, v7 is v1, v1.values, v7.values 
    461466    2 False <a, b, c, d, e> <f> 
     
    466471 
    467472    >>> v8, s = Orange.data.variable.make("a", Orange.data.Type.Discrete, 
    468             ["a", "b", "c", "d", "e"], None, Orange.data.variable.Variable.MakeStatus.OK) 
     473            ["a", "b", "c", "d", "e"], None, Orange.data.variable.MakeStatus.OK) 
    469474    >>> print s, v8 is v1, v1.values, v8.values 
    470475    0 False <a, b, c, d, e> <a, b, c, d, e> 
     
    485490make = orange.Variable.make 
    486491retrieve = orange.Variable.get_existing 
     492MakeStatus = orange.Variable.MakeStatus 
    487493del orange 
Note: See TracChangeset for help on using the changeset viewer.