Changeset 9891:66ee6522a40f in orange for Orange/misc/__init__.py


Ignore:
Timestamp:
02/07/12 10:36:00 (2 years ago)
Author:
gregorr
Branch:
default
Children:
9892:3b220d15fb39, 9899:e4d688c99b4d
rebase_source:
9008685954e62e9d1b8d559c6cb195741af07d6f
Message:

SymMatrix documentation (data -> misc).

File:
1 edited

Legend:

Unmodified
Added
Removed
  • Orange/misc/__init__.py

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