1.. currentmodule:: Orange.data
2
3############################
4Data Instance (``instance``)
5############################
6
7Class :obj:`Instance` represents a data instance, typically retrieved from a
8:obj:`Orange.data.Table` or :obj:`Orange.data.sql.SqlTable`. The base class
9contains a copy of the data; modifying does not change the data in the storage
10from which the instance was retrieved. Derived classes
11(e.g. :obj:`Orange.data.table.RowInstance`) can represent views into various
12data storages, therefore changing them actually changes the data.
13
14Like data tables, every data instance is associated with a domain and its
15data is split into attributes, classes, meta attributes and the weight. Its
16constructor thus requires a domain and, optionally, data. For the following
17example, we borrow the domain from the Iris dataset. ::
18
19    >>> from Orange.data import Table, Instance
20    >>> iris = Table("iris")
21    >>> inst = Instance(iris.domain, [5.2, 3.8, 1.4, 0.5, "Iris-virginica"])
22    >>> inst
23    [5.2, 3.8, 1.4, 0.5 | Iris-virginica]
24    >>> inst0 = Instance(iris.domain)
25    >>> inst0
26    [?, ?, ?, ? | ?]
27
28The instance's data can be retrieved through attributes :obj:`x`, :obj:`y` and
29:obj:`metas`. ::
30
31    >>> inst.x
32    array([ 5.2,  3.8,  1.4,  0.5])
33    >>> inst.y
34    array([ 2.])
35    >>> inst.metas
36    array([], dtype=object)
37
38Other utility functions provide for easier access to the instances data. ::
39
40    >>> inst.get_class()
41    Value('iris', Iris-virginica)
42    >>> for e in inst.attributes():
43    ...     print(e)
44    ...
45    5.2
46    3.8
47    1.4
48    0.5
49
50.. autoclass:: Instance
51    :members:
52
53    Constructor requires a domain and the data as numpy array, an existing
54    instance from the same or another domain or any Python iterable.
55
56    Domain can be omitted it the data is given as an existing data instances.
57
58    When the instance is not from the given domain, Orange converts it.
59
60        >>> from Orange.preprocess import DomainDiscretizer
61        >>> discretizer = DomainDiscretizer()
62        >>> d_iris = discretizer(iris)
63        >>> d_inst = Instance(d_iris, inst)
64
65
66
67Rows of Data Tables
68-------------------
69
70.. autoclass:: RowInstance
71    :members:
72
73    `RowInstance` is a specialization of :obj:`~Orange.data.Instance` that
74    represents a row of :obj:`Orange.data.Table`. `RowInstance` is returned
75    by indexing a `Table`.
76
77    The difference between `Instance` and `RowInstance` is that the latter
78    represents a view into the table: changing the `RowInstance` changes the
79    data in the table::
80
81        >>> iris[42]
82        [4.4, 3.2, 1.3, 0.2 | Iris-setosa]
83        >>> inst = iris[42]
84        >>> inst.set_class("Iris-virginica")
85        >>> iris[42]
86        [4.4, 3.2, 1.3, 0.2 | Iris-virginica]
87
88    Dense tables can also be modified directly through :obj:`x`, :obj:`y` and
89    :obj:`metas`. ::
90
91        >>> inst.x[0] = 5
92        >>> iris[42]
93        [5.0, 3.2, 1.3, 0.2 | Iris-virginica]
94
95    Sparse tables cannot be changed in this way.
96