Changeset 9756:51b322a353ef in orange


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

Finished polishing documentation for Orange.data.value

File:
1 edited

Legend:

Unmodified
Added
Removed
  • docs/reference/rst/Orange.data.value.rst

    r9372 r9756  
    1111    distribution, or a string. 
    1212 
    13     Values are not references. For instance, when taking a value from 
    14     a data instance (e.g. ``value = data[2]``), the result is a copy of 
    15     the value; changing it does not affect the original data instance. 
     13    Values are not assigned as references. For instance, 
     14    when taking a value from a data instance (e.g. ``value = data[2]``), 
     15    the result is a copy of the value; changing it does not affect the 
     16    original data instance. 
    1617 
    1718    .. attribute:: value 
    1819 
    19         The actual value. Values of discrete and continuous variables 
    20         are internally stored as integers or floating point numbers, 
    21         respectively. This attribute gives a number for continuous 
    22         variables and strings for discrete. If variable descriptor 
    23         (:obj:`variable`) is not :obj:`None`, the string is a symbolic value 
    24         for the attribute, otherwise it contains a number enclosed in 
    25         <> brackets. If value unknown, the result is a string '?', '~' 
    26         or '.'  for don't know, don't care and other, respectively. 
     20        The actual value. 
     21 
     22        * If the `Value` is numeric, `value` is a number. 
     23 
     24        * If it is discrete and the variable descriptor is present 
     25          (:obj:`variable` is not :obj:`None`), `value` is a string with 
     26          the symbolic value (as retrieved from 
     27          :obj:`Orange.data.variable.Discrete.values`). 
     28 
     29        * If it is discrete and the variable descriptor is unknown, 
     30          `value` is a string with the number representing the value 
     31          index, enclosed in brackets. 
     32 
     33        * If the value is missing, `value` is a string ``'?'``, ``'~'`` 
     34          or ``'.'``  for don't know, don't care and other, respectively. 
    2735 
    2836    .. attribute:: svalue 
    2937 
    30         Instance of :obj:`Orange.core.SomeValue`, such as 
    31         :obj:`Orange.data.StringValue`, 
     38        Stores a value that corresponds to a variable that is neither 
     39        :obj:`Orange.data.variable.Discrete` nor 
     40        :obj:`Orange.data.variable.Continuous` or a distribution of a 
     41        discrete or continuous value. 
     42 
     43        This attribute is most often used for values of 
     44        :obj:`Orange.data.variable.StringVariable`; in that case `svalue` 
     45        is an instance of :obj:`Orange.data.StringValue`. Distributions 
     46        are seldom used; when `svalue` contains a distribution, it is 
     47        represented with an instance of 
    3248        :obj:`Orange.statistics.distribution.Discrete` or 
    33         :obj:`Orange.statistics.distribution.Continuous`, which is 
    34         used for storing values of non-numeric and non-discrete types. 
     49        :obj:`Orange.statistics.distribution.Continuous`. 
    3550 
    3651    .. attribute:: variable  
    3752 
    38         Descriptor related to the value. Can be :obj:`None`. 
     53        Descriptor related to the value. Can be ``None``. 
    3954 
    4055    .. attribute:: var_type 
    4156 
    4257        Read-only descriptor that gives the variable type. Can be 
    43         ``Orange.data.Type.Discrete``, ``Orange.data.Type.Continuous``, 
    44         ``Orange.data.Type.String`` or ``Orange.data.Type.Other``. 
     58        :obj:`Orange.data.Type.Discrete`, :obj:`Orange.data.Type.Continuous`, 
     59        :obj:`Orange.data.Type.String` or :obj:`Orange.data.Type.Other`. 
    4560 
    4661    .. attribute:: value_type 
    4762 
    48         Tells whether the value is known or not. Can be 
    49         ``Orange.data.Value.Regular``, ``Orange.data.Value.DC``, 
    50         ``Orange.data.Value.DK``. 
     63        Tells whether the value is known 
     64        (:obj:`Orange.data.Value.Regular`) or not 
     65        (:obj:`Orange.data.Value.DC`. :obj:`Orange.data.Value.DK`). 
    5166 
    5267    .. method:: __init__(variable[, value]) 
    5368 
    54     Construct a value with the given descriptor. Value can be any 
    55      object, that the descriptor understands. For discrete 
    56      variables, this can be a string or an index, for continuous 
    57      it can be a string or a number. If the value is omitted, it 
    58      is set to unknown (DK). :: 
     69        Construct a value with the given descriptor. Value can be any 
     70         object that the descriptor understands. For discrete 
     71         variables, this can be a string or an index (an integer number), 
     72         for continuous it can be a string or a number. If the value is 
     73         omitted, it is set to unknown (:obj:`Orange.data.Value.DK`). :: 
    5974 
    6075             import Orange 
     
    7186        :param variable: variable descriptor 
    7287        :type variables: Orange.data.variable.Variable 
    73     :param value: A value 
    74     :type value: int, float or string, or another type accepted by the given descriptor 
     88        :param value: A value 
     89        :type value: int, float or string, or another type accepted by descriptor 
    7590 
    7691    .. method:: __init__(value) 
     
    7893        Construct either a discrete value, if the argument is an 
    7994        integer, or a continuous one, if the argument is a 
    80         floating-point number. 
     95        floating-point number. Descriptor is set to ``None``. 
    8196 
    8297    :param value: A value 
     
    91106    .. method:: is_DC() 
    92107 
    93         Return :obj:`True` if value is "don't care". 
     108        Return ``True`` if value is "don't care". 
    94109 
    95110    .. method:: is_DK() 
    96111 
    97         Return :obj:`True` if value is "don't know". 
     112        Return ``True`` if value is "don't know". 
    98113 
    99114    .. method:: is_special() 
    100115 
    101         Return :obj:`True` if value is either "don't know" or "don't 
    102         care". 
     116        Return ``True`` if value is either "don't know" or "don't care". 
    103117 
    104     Discrete and continuous values can be cast to Python types :obj:`int`, 
    105     :obj:`float`, :obj:`long`, to strings and to boolean values. A value is 
    106     considered true if it is not undefined. Continuous values support arithmetic 
    107     operations. 
     118Casting and comparison of values 
     119-------------------------------- 
    108120 
    109     Values can be compared between themselves or with ordinary 
    110     numbers. All discrete variables are treated as ordinal; values are 
    111     compared by their respective indices and not in alphabetical order 
    112     of their symbolic representations. When comparing values 
    113     corresponding to different descriptors, Orange checks whether the 
    114     order is unambiguous. Here are two such values:: 
     121Discrete and continuous values can be cast to Python types :obj:`int`, 
     122:obj:`float`, :obj:`long`, to strings and to boolean values. A value is 
     123considered true if it is not undefined. Continuous values support 
     124arithmetic operations. 
    115125 
    116         deg3 = Orange.data.variable.Discrete("deg3", 
    117                                        values=["little", "medium", "big"]) 
    118         deg4 = orange.data.variable.Discrete("deg4", 
    119                                        values=["tiny", "little", "big", "huge"]) 
    120         val3 = orange.Value(deg3) 
    121         val4 = orange.Value(deg4) 
    122         val3.value = "medium" 
    123         val4.value = "little" 
     126Values can be compared with each other or with ordinary numbers. 
     127All discrete variables are treated as ordinal; values are 
     128compared by their respective indices and not in alphabetical order 
     129of their symbolic representations. When comparing values 
     130corresponding to different descriptors, Orange checks whether the 
     131order is unambiguous. Here are two such values:: 
    124132 
    125     Given this order, "medium" and "little" can be compared, since it is known, 
    126     from ``deg3``, that "little" is less than "medium". :: 
     133    deg3 = Orange.data.variable.Discrete( 
     134        "deg3", values=["little", "medium", "big"]) 
     135    deg4 = orange.data.variable.Discrete( 
     136        "deg4", values=["tiny", "little", "big", "huge"]) 
     137    val3 = orange.Value(deg3) 
     138    val4 = orange.Value(deg4) 
     139    val3.value = "medium" 
     140    val4.value = "little" 
    127141 
    128         val3.value = "medium" 
    129         val4.value = "huge" 
     142Given this order, "medium" and "little" can be compared since it is known, 
     143from ``deg3``, that "little" is less than "medium". :: 
    130144 
    131     These two values cannot be compared since they do not appear in the same 
    132     variable. (Orange is not smart enough to discover that medium is less than 
    133     big and huge is more than big.) 
     145    val3.value = "medium" 
     146    val4.value = "huge" 
    134147 
    135     Two values also cannot be compared when they have different order in the two variables.  
     148These two values cannot be compared since they do not appear in the same 
     149variable. (Orange cannot use transitivity to conclude that medium is 
     150less than huge since medium is less than big and big is less than 
     151huge.) 
     152 
     153Two values also cannot be compared when they have different order in 
     154the two variables. 
Note: See TracChangeset for help on using the changeset viewer.