source: orange/orange/doc/Orange/rst/Orange.data.value.rst @ 7724:1b8c1f47bbae

Revision 7724:1b8c1f47bbae, 5.0 KB checked in by janezd <janez.demsar@…>, 3 years ago (diff)

Added documentation for Orange.data.Value

Line 
1.. py:currentmodule:: Orange.data
2
3======
4Values
5======
6
7.. class:: Value
8
9    Contains a value of a variable. Value can be discrete,
10    continuous or of some other type, like discrete or continuous
11    distribution, or a string.
12
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.
16
17    .. attribute:: value
18
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.
27
28    .. attribute:: svalue
29
30        Instance of :obj:`Orange.core.SomeValue`, such as
31        :obj:`Orange.data.StringValue`,
32        :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.
35
36    .. attribute:: variable
37
38        Descriptor related to the value. Can be :obj:`None`.
39
40    .. attribute:: var_type
41
42        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``.
45
46    .. attribute:: value_type
47
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``.
51
52    .. method:: __init__(variable[, value])
53
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). ::
59
60             import Orange
61             v = Orange.data.variable.Discrete("fruit", values=["plum", "orange", "apple"])
62             an_apple = Orange.data.Value(v, "apple")
63             another_apple = Orange.data.Value(v, 2)
64             unknown_fruit = Orange.data.Value(v)
65
66             v2 = Orange.data.variable.Continuous("iq")
67             genius = Orange.data.Value(v2, 180)
68             troll = Orange.data.Value(v2, "42")
69             stranger = Orange.data.value(v2)
70
71        :param variable: variable descriptor
72        :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
75
76    .. method:: __init__(value)
77
78        Construct either a discrete value, if the argument is an
79        integer, or a continuous one, if the argument is a
80        floating-point number.
81
82    :param value: A value
83    :type value: int or float
84
85    .. method:: native()
86
87        Return the value in a "native" Python form: strings for
88        discrete and undefined values and floating-point numbers for
89        continuous values.
90
91    .. method:: is_DC()
92
93        Return :obj:`True` if value is "don't care".
94
95    .. method:: is_DK()
96
97        Return :obj:`True` if value is "don't know".
98
99    .. method:: is_special()
100
101        Return :obj:`True` if value is either "don't know" or "don't
102        care".
103
104    Discrete and continuous values can be cast to Python types
105    :obj:`int`, :obj:`float`, :obj:`long`, to strings and to boolean
106    values. A value is true if it is not undefined. Continuous values
107    support arithmetic operations.
108
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::
115
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"
124
125    Given this order, "medium" and "little" can be compared, since it is known,
126    from ``deg3``, that "little" is less than "medium". ::
127
128        val3.value = "medium"
129        val4.value = "huge"
130
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.)
134
135    Two values also cannot be compared when they have different order in the two variables.
Note: See TracBrowser for help on using the repository browser.