source: orange/docs/reference/rst/Orange.data.value.rst @ 9927:d6ca7b346864

Revision 9927:d6ca7b346864, 5.5 KB checked in by markotoplak, 2 years ago (diff)

data.variable -> feature.

Line 
1.. py:currentmodule:: Orange.data
2
3==================
4Values (``Value``)
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 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.
17
18    .. attribute:: value
19
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.feature.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.
35
36    .. attribute:: svalue
37
38        Stores a value that corresponds to a variable that is neither
39        :obj:`Orange.feature.Discrete` nor
40        :obj:`Orange.feature.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.feature.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
48        :obj:`Orange.statistics.distribution.Discrete` or
49        :obj:`Orange.statistics.distribution.Continuous`.
50
51    .. attribute:: variable
52
53        Descriptor related to the value. Can be ``None``.
54
55    .. attribute:: var_type
56
57        Read-only descriptor that gives the variable type. Can be
58        :obj:`Orange.feature.Type.Discrete`, :obj:`Orange.feature.Type.Continuous`,
59        :obj:`Orange.feature.Type.String` or :obj:`Orange.feature.Type.Other`.
60
61    .. attribute:: value_type
62
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`).
66
67    .. method:: __init__(variable[, value])
68
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`). ::
74
75             import Orange
76             v = Orange.feature.Discrete("fruit", values=["plum", "orange", "apple"])
77             an_apple = Orange.data.Value(v, "apple")
78             another_apple = Orange.data.Value(v, 2)
79             unknown_fruit = Orange.data.Value(v)
80
81             v2 = Orange.feature.Continuous("iq")
82             genius = Orange.data.Value(v2, 180)
83             troll = Orange.data.Value(v2, "42")
84             stranger = Orange.data.value(v2)
85
86        :param variable: variable descriptor
87        :type variables: Orange.feature.Descriptor
88        :param value: A value
89        :type value: int, float or string, or another type accepted by descriptor
90
91    .. method:: __init__(value)
92
93        Construct either a discrete value, if the argument is an
94        integer, or a continuous one, if the argument is a
95        floating-point number. Descriptor is set to ``None``.
96
97    :param value: A value
98    :type value: int or float
99
100    .. method:: native()
101
102        Return the value in a "native" Python form: strings for
103        discrete and undefined values and floating-point numbers for
104        continuous values.
105
106    .. method:: is_DC()
107
108        Return ``True`` if value is "don't care".
109
110    .. method:: is_DK()
111
112        Return ``True`` if value is "don't know".
113
114    .. method:: is_special()
115
116        Return ``True`` if value is either "don't know" or "don't care".
117
118Casting and comparison of values
119--------------------------------
120
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.
125
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::
132
133    deg3 = Orange.feature.Discrete(
134        "deg3", values=["little", "medium", "big"])
135    deg4 = orange.feature.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"
141
142Given this order, "medium" and "little" can be compared since it is known,
143from ``deg3``, that "little" is less than "medium". ::
144
145    val3.value = "medium"
146    val4.value = "huge"
147
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 TracBrowser for help on using the repository browser.