source: orange/docs/reference/rst/Orange.data.symmatrix.rst @ 9372:aef193695ea9

Revision 9372:aef193695ea9, 4.7 KB checked in by mitar, 2 years ago (diff)

Moved documentation to the separate directory.

Line 
1.. py:currentmodule:: Orange.data
2
3================================
4Symmetric matrix (``SymMatrix``)
5================================
6
7:obj:`SymMatrix` implements symmetric matrices of size fixed at
8construction time (and stored in :obj:`SymMatrix.dim`).
9
10.. class:: SymMatrix
11
12    .. attribute:: dim
13   
14        Matrix dimension.
15           
16    .. attribute:: matrix_type
17
18        Can be ``SymMatrix.Lower`` (0), ``SymMatrix.Upper`` (1),
19        ``SymMatrix.Symmetric`` (2, default), ``SymMatrix.Lower_Filled`` (3) or
20        ``SymMatrix.Upper_Filled`` (4).
21
22        If the matrix type is ``Lower`` or ``Upper``, indexing
23        above or below the diagonal, respectively, will fail.
24        With ``Lower_Filled`` and ``Upper_Filled``,
25        the elements upper or lower, respectively, still
26        exist and are set to zero, but they cannot be modified. The
27        default matrix type is ``Symmetric``, but can be changed
28        at any time.
29
30        If matrix type is ``Upper``, it is printed as:
31
32        >>> m.matrix_type = m.Upper
33        >>> print m
34        (( 1.000,  2.000,  3.000,  4.000),
35         (         4.000,  6.000,  8.000),
36         (                 9.000, 12.000),
37         (                        16.000))
38
39        Changing the type to ``Lower_Filled`` changes the printout to
40
41        >>> m.matrix_type = m.Lower_Filled
42        >>> print m
43        (( 1.000,  0.000,  0.000,  0.000),
44         ( 2.000,  4.000,  0.000,  0.000),
45         ( 3.000,  6.000,  9.000,  0.000),
46         ( 4.000,  8.000, 12.000, 16.000))
47   
48    .. method:: __init__(dim[, default_value])
49
50        Construct a symmetric matrix of the given dimension.
51
52        :param dim: matrix dimension
53        :type dim: int
54
55        :param default_value: default value (0 by default)
56        :type default_value: double
57       
58       
59    .. method:: __init__(instances)
60
61        Construct a new symmetric matrix containing the given data instances.
62        These can be given as Python list containing lists or tuples.
63
64        :param instances: data instances
65        :type instances: list of lists
66       
67        The following example fills a matrix created above with
68        data in a list::
69
70            import Orange
71            m = [[],
72                 [ 3],
73                 [ 2, 4],
74                 [17, 5, 4],
75                 [ 2, 8, 3, 8],
76                 [ 7, 5, 10, 11, 2],
77                 [ 8, 4, 1, 5, 11, 13],
78                 [ 4, 7, 12, 8, 10, 1, 5],
79                 [13, 9, 14, 15, 7, 8, 4, 6],
80                 [12, 10, 11, 15, 2, 5, 7, 3, 1]]
81                   
82            matrix = Orange.data.SymMatrix(m)
83
84        SymMatrix also stores diagonal elements. They are set
85        to zero, if they are not specified. The missing elements
86        (shorter lists) are set to zero as well. If a list
87        spreads over the diagonal, the constructor checks
88        for asymmetries. For instance, the matrix
89
90        ::
91
92            m = [[],
93                 [ 3,  0, f],
94                 [ 2,  4]]
95   
96        is only OK if f equals 2. Finally, no row can be longer
97        than matrix size. 
98
99    .. method:: get_values()
100   
101        Return all matrix values in a Python list.
102
103    .. method:: get_KNN(i, k)
104   
105        Return k columns with the lowest value in the i-th row.
106       
107        :param i: i-th row
108        :type i: int
109       
110        :param k: number of neighbors
111        :type k: int
112       
113    .. method:: avg_linkage(clusters)
114   
115        Return a symmetric matrix with average distances between given clusters. 
116     
117        :param clusters: list of clusters
118        :type clusters: list of lists
119       
120    .. method:: invert(type)
121   
122        Invert values in the symmetric matrix.
123       
124        :param type: 0 (-X), 1 (1 - X), 2 (max - X), 3 (1 / X)
125        :type type: int
126
127    .. method:: normalize(type)
128   
129        Normalize values in the symmetric matrix.
130       
131        :param type: 0 (normalize to [0, 1] interval), 1 (Sigmoid)
132        :type type: int
133       
134       
135-------------------
136Indexing
137-------------------
138
139For symmetric matrices the order of indices is not important:
140if ``m`` is a SymMatrix, then ``m[2, 4]`` addresses the same element as ``m[4, 2]``.
141
142.. literalinclude:: code/symmatrix.py
143    :lines: 1-6
144
145Although only the lower left half of the matrix was set explicitely,
146the whole matrix is constructed.
147
148>>> print m
149(( 1.000,  2.000,  3.000,  4.000),
150 ( 2.000,  4.000,  6.000,  8.000),
151 ( 3.000,  6.000,  9.000, 12.000),
152 ( 4.000,  8.000, 12.000, 16.000))
153 
154Entire rows are indexed with a single index. They can be iterated
155over in a for loop or sliced (with, for example, ``m[:3]``):
156
157>>> print m[1]
158(3.0, 6.0, 9.0, 0.0)
159>>> m.matrix_type = m.Lower
160>>> for row in m:
161...     print row
162(1.0,)
163(2.0, 4.0)
164(3.0, 6.0, 9.0)
165(4.0, 8.0, 12.0, 16.0)
166
Note: See TracBrowser for help on using the repository browser.