Changeset 9008:947c182800b5 in orange


Ignore:
Timestamp:
09/23/11 21:04:02 (3 years ago)
Author:
miha <miha.stajdohar@…>
Branch:
default
Convert:
416218ee214d77b7bbaba2c60546b4f50c75789f
Message:
 
File:
1 edited

Legend:

Unmodified
Added
Removed
  • orange/doc/Orange/rst/Orange.data.symmatrix.rst

    r8996 r9008  
    66 
    77Class `Orange.data.SymMatrix` is symmetric (square) matrix of size fixed at  
    8 construction time (and stored to the attribute dim). The constructor expects a  
    9 sequence of sequences (eg. a list of lists, a list of tuples...) or the matrix  
    10 dimension. An optional additional argument gives the default value; the default  
    11 is 0. 
     8construction time (and stored to the attribute dim). 
    129 
     10.. class:: SymMatrix 
    1311 
    14 For instance, a nice list to initialize the matrix with looks like this: 
     12    .. attribute:: dim 
     13     
     14        Matrix dimension. 
     15             
     16    .. attribute:: matrix_type  
    1517 
    16 Example from :obj:`Orange.clustering.hierarchical` (Example 1 - Toy matrix) 
    17 :: 
     18        Value can be set to SymMatrix.Lower (0), SymMatrix.Upper (1),  
     19        SymMatrix.Symmetric (2, default), SymMatrix.Lower_Filled (3) or 
     20        SymMatrix.Upper_Filled (4).  
     21         
     22        By setting it to Lower or Upper, we limit the matrix to the lower or  
     23        upper half. Attempts to index anything above or below the diagonal,  
     24        respectively, will yield an error. With Lower_Filled and Upper_Field,  
     25        the elements of the other half (upper or lower, respectively) still  
     26        exist, but are set to zero and can be read, but cannot be modified. The  
     27        matrix type is by default initially set to symmetric, but can be changed  
     28        at any time. 
    1829 
    19     import Orange 
    20     from Orange.clustering import hierarchical 
    21     m = [[], 
    22      [ 3], 
    23      [ 2, 4], 
    24      [17, 5, 4], 
    25      [ 2, 8, 3, 8], 
    26      [ 7, 5, 10, 11, 2], 
    27      [ 8, 4, 1, 5, 11, 13], 
    28      [ 4, 7, 12, 8, 10, 1, 5], 
    29      [13, 9, 14, 15, 7, 8, 4, 6], 
    30      [12, 10, 11, 15, 2, 5, 7, 3, 1]] 
    31     matrix = Orange.data.SymMatrix(m) 
     30        If matrix type is changed to SymMatrix.Upper, it gets printed as 
    3231 
    33 This matrix, meant as a distance matrix, is used in example from the description  
    34 of hierarchical clustering. SymMatrix also stores the diagonal elements; here  
    35 they are not specified, so they are set to 0. The matrix needn't by so nice. If  
    36 any line was shorter, the missing elements would be set to 0 as well. Any line  
    37 could also be longer, spreading across the diagonal, in which case the  
    38 constructor would check for asymmetries. For instance, if the matrix started  
    39 by 
    40 :: 
     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)) 
    4138 
    42     m = [[], 
    43          [ 3,  0, f], 
    44          [ 2,  4], ... 
    45          
    46 this would only be OK if f equals 2; otherwise, the matrix would be asymmetric. 
     39        Changing the type to SymMatrix.Lower_Filled will change the printout to 
    4740 
    48 Finally, no line can be longer than the total number of lines. Here we have 10  
    49 rows, so no row may have more than 10 columns. 
     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]) 
    5049 
    51 So much for construction. Indexing is implemented so that order of indices is  
    52 unimportant (unless set otherwise, see below), eg, if m is an instance of  
     50        Construct an empty symmetric matrix with 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 the symmetric matrix created above with 
     68        some data from 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 the diagonal elements. Here they are not  
     85        specified, so they are set to 0. If any line was shorter, the missing  
     86        elements would be set to 0 as well. Any line could also be longer,  
     87        spreading across the diagonal, in which case the constructor would check 
     88        for asymmetries. For instance, if the matrix started by:: 
     89 
     90            m = [[], 
     91                 [ 3,  0, f], 
     92                 [ 2,  4], ... 
     93     
     94        this would only be OK if f equals 2; otherwise, the matrix would be  
     95        asymmetric. 
     96 
     97        Finally, no line can be longer than the total number of lines. Here we  
     98        have 10 rows, so no row may have more than 10 columns. 
     99 
     100    .. method:: get_values() 
     101     
     102        Return all matrix values in a Python list. 
     103 
     104    .. method:: get_KNN(i, k) 
     105     
     106        Return k columns with the lowest value in the i-th row.  
     107         
     108        :param i: i-th row 
     109        :type i: int 
     110         
     111        :param k: number of neighbors 
     112        :type k: int 
     113         
     114    .. method:: avg_linkage(clusters) 
     115     
     116        Return a symmetric matrix with average distances between given clusters.   
     117       
     118        :param clusters: list of clusters 
     119        :type clusters: list of lists 
     120         
     121    .. method:: invert(type) 
     122     
     123        Invert values in the symmetric matrix. 
     124         
     125        :param type: 0 (-X), 1 (1 - X), 2 (max - X), 3 (1 / X) 
     126        :type type: int 
     127 
     128    .. method:: normalize(type) 
     129     
     130        Normalize values in the symmetric matrix. 
     131         
     132        :param type: 0 (normalize to [0, 1] interval), 1 (Sigmoid) 
     133        :type type: int 
     134         
     135         
     136------------------- 
     137Indexing 
     138------------------- 
     139 
     140Indexing is implemented so that order of indices is unimportant (unless set  
     141otherwise with the matrix_type attribute). For example, if m is an instance of  
    53142SymMatrix, then m[2, 4] addresses the same element as m[4, 2]. 
    54143 
    55  
    56 part of `symmatrix.py`_ 
     144`symmatrix.py`_ 
    57145     
    58146.. literalinclude:: code/symmatrix.py 
    59147    :lines: 1-6 
    60148 
    61 Although we set only the lower left half of the matrix (if we interpret the  
    62 first index, i, as the row index), we have actually constructed a whole  
    63 symmetric matrix. 
     149Although only the lower left half of the matrix is set , we have actually  
     150constructed a whole symmetric matrix. 
    64151 
    65152>>> print m 
     
    73160and the same element). 
    74161 
    75 The matrix has an attribute matrixType whose value can be set to SymMatrix.Lower  
    76 (0), SymMatrix.Upper (1), SymMatrix.Symmetric (2, default),  
    77 SymMatrix.Lower_Filled (3), SymMatrix.Upper_Filled (4). By setting it to Lower  
    78 or Upper, we limit the matrix to the lower or upper half; attempts to index  
    79 anything above or below the diagonal, respectively, will yield an error. With  
    80 Lower_Filled and Upper_Field, the elements of the other half (upper or lower,  
    81 respectively) still exist, but are set to zero and can be read, but cannot be  
    82 modified. The matrix type is by default initially set to symmetric, but can be  
    83 changed at any time. If it is, for instance, changed from lower to upper, the  
    84 matrix gets transposed (actually, nothing really happens, the change only  
    85 affects indexing (and printing) while the internal matrix representation stays  
    86 the same, so changing the matrix type takes no time). 
    87  
    88 If we, for instance, change the matrix type of the above matrix to  
    89 SymMatrix.Upper, it gets printed as 
    90  
    91 >>> m.matrixType = m.Upper 
    92 >>> print m 
    93 (( 1.000,  2.000,  3.000,  4.000), 
    94  (         4.000,  6.000,  8.000), 
    95  (                 9.000, 12.000), 
    96  (                        16.000)) 
    97  
    98 Changing the type to SymMatrix.Lower_Filled will change the printout to 
    99  
    100 >>> m.matrixType = m.Lower_Filled 
    101 >>> print m 
    102 (( 1.000,  0.000,  0.000,  0.000), 
    103  ( 2.000,  4.000,  0.000,  0.000), 
    104  ( 3.000,  6.000,  9.000,  0.000), 
    105  ( 4.000,  8.000, 12.000, 16.000)) 
    106  
    107 It is also possible to index entire rows by using a single index instead of two. 
     162Index entire rows by using a single index instead of two: 
    108163 
    109164>>> print m[1] 
    110165(3.0, 6.0, 9.0, 0.0) 
    111166 
    112 In the similar manner, you can iterate over the matrix using a for loop. 
     167Iterate over the matrix using a for loop: 
    113168 
    114 >>> m.matrixType = m.Lower 
     169>>> m.matrix_type = m.Lower 
    115170>>> for row in m: 
    116171...     print row 
     
    120175(4.0, 8.0, 12.0, 16.0) 
    121176 
    122 Slicing also works, but what you get by taking, for instance, m[:3] is a tuple  
    123 containing the first three lines of the matrix (again represented as tuples). 
    124  
    125 Started to wonder why always those annoying tuples and not lists that you can  
    126 change as you will? To give you a clear message about one thing you cannot do  
    127 with the matrix: you cannot change its contents by manipulating the rows you get  
    128 by row indexing or slicing. Also, you cannot assign whole rows to matrices: 
    129  
    130 >>> m[1] = (0, 0, 0, 0) 
    131 Traceback (most recent call last): 
    132   File "<interactive input>", line 1, in ? 
    133 IndexError: two integer indices expected 
    134  
    135 If you want to manipulate the row contents for your purposes, knowing that it  
    136 doesn't change the matrix, convert it to list by calling list(m[i]). 
     177Slicing also works. For example, m[:3] is a tuple containing the first three  
     178lines of the matrix (again represented as tuples). 
    137179 
    138180.. _symmatrix.py: code/symmatrix.py 
Note: See TracChangeset for help on using the changeset viewer.