Changeset 9050:3564e52fa38d in orange


Ignore:
Timestamp:
10/03/11 15:00:43 (3 years ago)
Author:
ales_erjavec <ales.erjavec@…>
Branch:
default
Convert:
111c1ecbc7293028355dba61e404fdb03b6e53f2
Message:

More documentation for Orange.clustering.hierarchical.
Added deprecated_function_name deprecation utility.
Documentation of Orange.misc.ConsoleProgressBar.

Location:
orange/Orange
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • orange/Orange/clustering/hierarchical.py

    r9034 r9050  
    434434 
    435435Utility Functions 
    436 ================= 
     436----------------- 
    437437 
    438438.. autofunction:: clustering 
     
    465465                        HierarchicalClusterList 
    466466 
    467 from Orange.misc import progressBarMilestones 
     467from Orange.misc import progress_bar_milestones, deprecated_keywords 
    468468                         
    469469import sys 
     
    475475 
    476476def clustering(data, 
    477                distanceConstructor=orange.ExamplesDistanceConstructor_Euclidean, 
     477               distance_constructor=orange.ExamplesDistanceConstructor_Euclidean, 
    478478               linkage=AVERAGE, 
    479479               order=False, 
    480                progressCallback=None): 
     480               progress_callback=None): 
    481481    """ Return a hierarchical clustering of the instances in a data set. 
    482482     
     
    499499    :type progress_callback: function 
    500500     
    501     """ 
    502     distance = distanceConstructor(data) 
     501    :rtype: :class:`HierarchicalCluster`  
     502     
     503    """ 
     504    distance = distance_constructor(data) 
    503505    matrix = orange.SymMatrix(len(data)) 
    504506    for i in range(len(data)): 
    505507        for j in range(i+1): 
    506508            matrix[i, j] = distance(data[i], data[j]) 
    507     root = HierarchicalClustering(matrix, linkage=linkage, progressCallback=(lambda value, obj=None: progressCallback(value*100.0/(2 if order else 1))) if progressCallback else None) 
     509    root = HierarchicalClustering(matrix, linkage=linkage, progress_callback=(lambda value, obj=None: progress_callback(value*100.0/(2 if order else 1))) if progress_callback else None) 
    508510    if order: 
    509         order_leaves(root, matrix, progressCallback=(lambda value: progressCallback(50.0 + value/2)) if progressCallback else None) 
     511        order_leaves(root, matrix, progress_callback=(lambda value: progress_callback(50.0 + value/2)) if progress_callback else None) 
    510512    return root 
    511513 
    512 def clustering_features(data, distance=None, linkage=orange.HierarchicalClustering.Average, order=False, progressCallback=None): 
     514clustering = \ 
     515    deprecated_keywords({"distanceConstructor": "distance_constructor", 
     516                         "progressCallback": "progress_callback"})(clustering) 
     517 
     518 
     519def clustering_features(data, distance=None, linkage=orange.HierarchicalClustering.Average, order=False, progress_callback=None): 
    513520    """ Return hierarchical clustering of attributes in a data set. 
    514521     
     
    531538    :type progress_callback: function 
    532539     
     540    :rtype: :class:`HierarchicalCluster` 
     541     
    533542    """ 
    534543    matrix = orange.SymMatrix(len(data.domain.attributes)) 
     
    536545        for a2 in range(a1): 
    537546            matrix[a1, a2] = (1.0 - orange.PearsonCorrelation(a1, a2, data, 0).r) / 2.0 
    538     root = orange.HierarchicalClustering(matrix, linkage=linkage, progressCallback=(lambda value, obj=None: progressCallback(value*100.0/(2 if order else 1))) if progressCallback else None) 
     547    root = orange.HierarchicalClustering(matrix, linkage=linkage, progress_callback=(lambda value, obj=None: progress_callback(value*100.0/(2 if order else 1))) if progress_callback else None) 
    539548    if order: 
    540         order_leaves(root, matrix, progressCallback=(lambda value: progressCallback(50.0 + value/2)) if progressCallback else None) 
     549        order_leaves(root, matrix, progressCallback=(lambda value: progress_callback(50.0 + value/2)) if progress_callback else None) 
    541550    return root 
    542551 
     552clustering_features = \ 
     553    deprecated_keywords({"progressCallback":"progress_callback"})(clustering_features) 
     554     
     555     
    543556def cluster_to_list(node, prune=None): 
    544557    """ Return a list of clusters down from the node of hierarchical clustering. 
     
    549562        with less then `prune` items will be left out of the list. 
    550563    :type node: int or `NoneType` 
     564     
     565    :rtype: list of :class:`HierarchicalCluster` instances 
    551566     
    552567    """ 
     
    558573    return [node] 
    559574 
     575 
    560576def top_clusters(root, k): 
    561577    """ Return k topmost clusters from hierarchical clustering. 
     
    565581    :param k: Number of top clusters. 
    566582    :type k: int 
     583     
     584    :rtype: list of :class:`HierarchicalCluster` instances 
    567585     
    568586    """ 
     
    583601    :type k: int 
    584602     
     603    :rtype: list-of-int 
     604     
    585605    """ 
    586606    clist = top_clusters(root, k) 
     
    611631    M = {} 
    612632    ordering = {} 
    613     visitedClusters = set() 
    614      
    615 #    def _optOrderingRecursive(tree): 
     633    visited_clusters = set() 
     634     
     635#    def opt_ordering_recursive(tree): 
    616636#        if len(tree)==1: 
    617637#            for leaf in tree: 
    618638#                M[tree, leaf, leaf] = 0 
    619639#        else: 
    620 #            _optOrderingRecursive(tree.left) 
    621 #            _optOrderingRecursive(tree.right) 
     640#            opt_ordering_recursive(tree.left) 
     641#            opt_ordering_recursive(tree.right) 
    622642#             
    623643#            Vl = set(tree.left) 
     
    633653##                    if True: #Improved search 
    634654#                    C = min([matrix[m, k] for m in other(u, Vll, Vlr) for k in other(w, Vrl, Vrr)]) 
    635 #                    orderedMs = sorted(other(u, Vll, Vlr), key=lambda m: M[tree_left, u, m]) 
    636 #                    orderedKs = sorted(other(w, Vrl, Vrr), key=lambda k: M[tree_right, w, k]) 
    637 #                    k0 = orderedKs[0] 
    638 #                    curMin = 1e30000  
    639 #                    curM = curK = None 
    640 #                    for m in orderedMs: 
    641 #                        if M[tree_left, u, m] + M[tree_right, w, k0] + C >= curMin: 
     655#                    ordered_m = sorted(other(u, Vll, Vlr), key=lambda m: M[tree_left, u, m]) 
     656#                    ordered_k = sorted(other(w, Vrl, Vrr), key=lambda k: M[tree_right, w, k]) 
     657#                    k0 = ordered_k[0] 
     658#                    cur_min = 1e30000  
     659#                    cur_m = cur_k = None 
     660#                    for m in ordered_m: 
     661#                        if M[tree_left, u, m] + M[tree_right, w, k0] + C >= cur_min: 
    642662#                            break 
    643 #                        for k in  orderedKs: 
    644 #                            if M[tree_left, u, m] + M[tree_right, w, k] + C >= curMin: 
     663#                        for k in  ordered_k: 
     664#                            if M[tree_left, u, m] + M[tree_right, w, k] + C >= cur_min: 
    645665#                                break 
    646 #                            testMin = M[tree_left, u, m] + M[tree_right, w, k] + matrix[m, k] 
    647 #                            if curMin > testMin: 
    648 #                                curMin = testMin 
    649 #                                curM = m 
    650 #                                curK = k 
    651 #                    M[tree, u, w] = M[tree, w, u] = curMin 
    652 #                    ordering[tree, u, w] = (tree_left, u, curM, tree_right, w, curK) 
    653 #                    ordering[tree, w, u] = (tree_right, w, curK, tree_left, u, curM) 
     666#                            test_min = M[tree_left, u, m] + M[tree_right, w, k] + matrix[m, k] 
     667#                            if cur_min > test_min: 
     668#                                cur_min = test_min 
     669#                                cur_m = m 
     670#                                cur_k = k 
     671#                    M[tree, u, w] = M[tree, w, u] = cur_min 
     672#                    ordering[tree, u, w] = (tree_left, u, cur_m, tree_right, w, cur_k) 
     673#                    ordering[tree, w, u] = (tree_right, w, cur_k, tree_left, u, cur_m) 
    654674##                    else: 
    655675##                    def MFunc((m, k)): 
     
    661681# 
    662682#            if progressCallback: 
    663 #                progressCallback(100.0 * len(visitedClusters) / len(tree.mapping)) 
    664 #                visitedClusters.add(tree) 
     683#                progressCallback(100.0 * len(visited_clusters) / len(tree.mapping)) 
     684#                visited_clusters.add(tree) 
    665685#     
    666686#    with recursion_limit(sys.getrecursionlimit() + len(tree)): 
    667 #        _optOrderingRecursive(tree) 
    668          
    669     def _optOrderingIterative(tree): 
     687#        opt_ordering_recursive(tree) 
     688         
     689    def opt_ordering_iterative(tree): 
    670690        if len(tree)==1: 
    671691            for leaf in tree: 
     
    687707#                    if True: #Improved search 
    688708                        C = min([matrix[m, k] for m in other(u, Vll, Vlr) for k in other(w, Vrl, Vrr)]) 
    689                         orderedMs = sorted(other(u, Vll, Vlr), key=lambda m: M[tree_left, u, m]) 
    690                         orderedKs = sorted(other(w, Vrl, Vrr), key=lambda k: M[tree_right, w, k]) 
    691                         k0 = orderedKs[0] 
    692                         curMin = 1e30000  
    693                         curM = curK = None 
    694                         for m in orderedMs: 
    695                             if M[tree_left, u, m] + M[tree_right, w, k0] + C >= curMin: 
     709                        ordered_m = sorted(other(u, Vll, Vlr), key=lambda m: M[tree_left, u, m]) 
     710                        ordered_k = sorted(other(w, Vrl, Vrr), key=lambda k: M[tree_right, w, k]) 
     711                        k0 = ordered_k[0] 
     712                        cur_min = 1e30000  
     713                        cur_m = cur_k = None 
     714                        for m in ordered_m: 
     715                            if M[tree_left, u, m] + M[tree_right, w, k0] + C >= cur_min: 
    696716                                break 
    697                             for k in  orderedKs: 
    698                                 if M[tree_left, u, m] + M[tree_right, w, k] + C >= curMin: 
     717                            for k in  ordered_k: 
     718                                if M[tree_left, u, m] + M[tree_right, w, k] + C >= cur_min: 
    699719                                    break 
    700                                 testMin = M[tree_left, u, m] + M[tree_right, w, k] + matrix[m, k] 
    701                                 if curMin > testMin: 
    702                                     curMin = testMin 
    703                                     curM = m 
    704                                     curK = k 
    705                         M[tree, u, w] = M[tree, w, u] = curMin 
    706                         ordering[tree, u, w] = (tree_left, u, curM, tree_right, w, curK) 
    707                         ordering[tree, w, u] = (tree_right, w, curK, tree_left, u, curM) 
     720                                test_min = M[tree_left, u, m] + M[tree_right, w, k] + matrix[m, k] 
     721                                if cur_min > test_min: 
     722                                    cur_min = test_min 
     723                                    cur_m = m 
     724                                    cur_k = k 
     725                        M[tree, u, w] = M[tree, w, u] = cur_min 
     726                        ordering[tree, u, w] = (tree_left, u, cur_m, tree_right, w, cur_k) 
     727                        ordering[tree, w, u] = (tree_right, w, cur_k, tree_left, u, cur_m) 
    708728#                    else: 
    709729#                        def MFunc((m, k)): 
     
    715735 
    716736#            if progressCallback: 
    717 #                progressCallback(100.0 * len(visitedClusters) / len(tree.mapping)) 
    718 #                visitedClusters.add(tree) 
    719     from Orange.misc import progressBarMilestones 
     737#                progressCallback(100.0 * len(visited_clusters) / len(tree.mapping)) 
     738#                visited_clusters.add(tree) 
    720739     
    721740    subtrees = postorder(tree) 
    722     milestones = progressBarMilestones(len(subtrees), 1000) 
     741    milestones = progress_bar_milestones(len(subtrees), 1000) 
    723742     
    724743    for i, subtree in enumerate(subtrees): 
    725         _optOrderingIterative(subtree) 
     744        opt_ordering_iterative(subtree) 
    726745        if progress_callback and i in milestones: 
    727746            progress_callback(100.0 * i / len(subtrees)) 
    728747 
    729 #    def _orderRecursive(tree, u, w): 
     748#    def order_recursive(tree, u, w): 
    730749#        """ Order the tree based on the computed optimal ordering.  
    731750#        """ 
     
    735754#        if len(left)>1 and m not in left.right: 
    736755#            left.swap() 
    737 #        _orderRecursive(left, u, m) 
     756#        order_recursive(left, u, m) 
    738757#         
    739758#        if len(right)>1 and k not in right.left: 
    740759#            right.swap() 
    741 #        _orderRecursive(right, k, w) 
    742          
    743     def _orderIterative(tree, u, w): 
     760#        order_recursive(right, k, w) 
     761         
     762    def order_iterative(tree, u, w): 
    744763        """ Order the tree based on the computed optimal ordering.  
    745764        """ 
     
    763782     
    764783#    with recursion_limit(sys.getrecursionlimit() + len(tree)): 
    765 #        _orderRecursive(tree, u, w) 
     784#        order_recursive(tree, u, w) 
    766785             
    767     _orderIterative(tree, u, w) 
     786    order_iterative(tree, u, w) 
    768787             
    769788 
     
    784803        tree.mapping.setattr("objects", objects) 
    785804 
     805 
    786806def order_leaves_cpp(tree, matrix, progress_callback=None): 
    787807    """ Order the leaves in the clustering tree (C++ implementation). 
     
    809829    Orange.core.HierarchicalClusterOrdering(tree, matrix, progress_callback=p) 
    810830 
    811 from Orange.misc import deprecated_keywords 
    812831order_leaves_cpp = deprecated_keywords({"progressCallback":"progress_callback"})(order_leaves_cpp) 
    813832order_leaves_py = deprecated_keywords({"progressCallback":"progress_callback"})(order_leaves_py) 
     
    816835order_leaves = order_leaves_py 
    817836     
    818 """ Matplotlib dendrogram ploting. 
     837""" 
     838Matplotlib dendrogram ploting. This is mostly untested, 
     839use dendrogram_draw funciton instead of this. 
     840 
    819841""" 
    820842try: 
     
    10531075         
    10541076         
    1055 """ Dendrogram ploting using Orange.misc.reander 
    10561077""" 
     1078Dendrogram ploting using Orange.misc.render 
     1079""" 
    10571080 
    10581081from Orange.misc.render import EPSRenderer, ColorPalette 
    10591082 
    10601083class DendrogramPlot(object): 
    1061     """ A class for drawing dendrograms 
    1062     Example: 
    1063     >>> a = DendrogramPlot(tree) 
     1084    """ A class for drawing dendrograms. 
     1085     
     1086    .. note:: ``dendrogram_draw`` function is a more convinient interface 
     1087        to the functionality provided by this class and.    
     1088         
     1089    Example:: 
     1090     
     1091        a = DendrogramPlot(tree) 
     1092        a.plot("tree.png", format="png") 
     1093         
    10641094    """ 
    10651095    def __init__(self, tree, attr_tree = None, labels=None, data=None, width=None, height=None, tree_height=None, heatmap_width=None, text_width=None,  
     
    12021232        self.renderer.save(filename, **kwargs) 
    12031233         
    1204 def dendrogram_draw(file, *args, **kwargs): 
    1205     """ Plot the dendrogram to `filename`. 
    1206      
    1207     .. todo:: Finish documentation. 
     1234         
     1235def dendrogram_draw(file, cluster, attr_cluster = None, labels=None, data=None, 
     1236                    width=None, height=None, tree_height=None, 
     1237                    heatmap_width=None, text_width=None,  spacing=2, 
     1238                    cluster_colors={}, color_palette=ColorPalette([(255, 0, 0), (0, 255, 0)]), 
     1239                    maxv=None, minv=None, gamma=None, 
     1240                    format=None): 
     1241    """ Plot the dendrogram to ``file``. 
     1242     
     1243    :param file: An  open file or a filename to store the image to. 
     1244    :type file: str or an file-like object suitable for writing. 
     1245     
     1246    :param cluster: An instance of :class:`HierarcicalCluster` 
     1247    :type cluster: :class:`HierarcicalCluster` 
     1248     
     1249    :param attr_cluster: An instance of :class:`HierarcicalCluster` for the attributes 
     1250        in ``data`` (unused if ``data`` is not supplied) 
     1251    :type attr_cluster: :class:`HierarcicalCluster` 
     1252     
     1253    :param labels: Labels for the ``cluster`` leaves. 
     1254    :type labels: list-of-strings 
     1255     
     1256    :param data: A data table for the (optional) heatmap. 
     1257    :type data: :class:`Orange.data.Table` 
     1258     
     1259    :param width: Image width. 
     1260    :type width: int 
     1261     
     1262    :param height: Image height. 
     1263    :type height: int 
     1264     
     1265    :param tree_height: Dendrogram tree height in the image. 
     1266    :type tree_height: int 
     1267     
     1268    :param heatmap_width: Heatmap width. 
     1269    :type heatmap_width: int 
     1270     
     1271    :param text_width: Text labels area width. 
     1272    :type text_width: int 
     1273     
     1274    :param spacing: Spacing between consecutive leaves. 
     1275    :type spacing: int 
     1276     
     1277    :param cluster_colors: A dictionary mapping :class:`HierarcicalCluster` 
     1278        instances in ``cluster`` to a RGB color 3-tuple. 
     1279    :type cluster_colors: dict 
     1280     
     1281    :param format: Output image format Currently supported formats are 
     1282        "png" (default), "eps" and "svg". You only need this arguement if the 
     1283        format cannot be deduced from the ``file`` argument. 
     1284         
     1285    :type format: str  
     1286     
    12081287    """ 
    12091288    import os 
     
    12111290    if isinstance(file, basestring): 
    12121291        name, ext = os.path.splitext(file) 
    1213         format = ext.lower().lstrip(".") 
    1214     else: 
    1215         format = kwargs.get("format", "png").lower() 
     1292        format = ext.lower().lstrip(".") or format 
     1293         
     1294    if format is None: 
     1295        format = "png" 
     1296         
    12161297    renderer = {"eps":EPSRenderer, "svg":SVGRenderer, "png":PILRenderer}.get(format, "png") 
    1217          
    1218     kwargs["renderer"] = renderer 
    1219     d = DendrogramPlot(*args, **kwargs) 
     1298     
     1299    d = DendrogramPlot(cluster, attr_cluster, labels, data, width, height, 
     1300                       tree_height, heatmap_width, text_width, spacing, 
     1301                       cluster_colors, color_palette, maxv, minv, gamma, 
     1302                       renderer=renderer) 
    12201303    if renderer is PILRenderer: 
    12211304        d.plot(file, format=format) 
     
    12281311    :param cluster: Cluster 
    12291312    :type cluster: :class:`HierarchicalCluster` 
     1313     
     1314    :rtype: list of :class:`HierarchicalCluster` instances 
    12301315     
    12311316    """ 
     
    12541339    :type cluster: :class:`HierarchicalCluster` 
    12551340     
     1341    :rtype: list of :class:`HierarchicalCluster` instances 
     1342     
    12561343    """ 
    12571344    order = [] 
     
    12651352     
    12661353     
    1267 def dendrogram_layout(root_cluster, expand_leaves=False): 
     1354def dendrogram_layout(cluster, expand_leaves=False): 
    12681355    """ Return a layout of the cluster dendrogram on a 2D plane. The return  
    12691356    value if a list of (subcluster, (start, center, end)) tuples where 
     
    12721359    in post-order. 
    12731360     
    1274     :param root_cluster: Cluster to layout. 
    1275     :type root_cluster: :class:`HierarchicalCluster` 
     1361    :param cluster: Cluster to layout. 
     1362    :type cluster: :class:`HierarchicalCluster` 
    12761363     
    12771364    :param expand_leaves: If True leaves will span proportional to the number 
    1278         of items they map, else all leaves will be the same width.  
    1279       
     1365        of items they contain, else all leaves will be the same width.  
     1366     
     1367    :rtype: list of (:class:`HierarchicalCluster`, (start, center, end)) tuples 
     1368     
    12801369    """ 
    12811370    result = [] 
    12821371    cluster_geometry = {} 
    12831372    leaf_idx = 0 
    1284     for cluster in postorder(root_cluster): 
     1373    for cluster in postorder(cluster): 
    12851374        if not cluster.branches: 
    12861375            if expand_leaves: 
     
    13101399    :type cluster: :class:`HierarchicalCluster` 
    13111400     
     1401    :rtype: :class:`HierarchicalCluster` 
     1402     
    13121403    """ 
    13131404    import copy 
     
    13231414    return clones[cluster] 
    13241415     
    1325 def pruned(root_cluster, level=None, height=None, condition=None): 
     1416def pruned(cluster, level=None, height=None, condition=None): 
    13261417    """ Return a new pruned clustering instance. 
    13271418     
    1328     .. note:: This uses :obj:`clone` to create a copy of the `root_cluster` 
     1419    .. note:: This uses :obj:`clone` to create a copy of the `cluster` 
    13291420        instance. 
    13301421     
     
    13441435    :type condition: function  
    13451436     
    1346     """ 
    1347     root_cluster = clone(root_cluster) 
    1348     prune(root_cluster, level, height, condition) 
    1349     return root_cluster 
    1350      
    1351      
    1352 def prune(root_cluster, level=None, height=None, condition=None): 
    1353     """ Prune clustering instance in place 
     1437    :rtype: :class:`HierarchicalCluster` 
     1438     
     1439    """ 
     1440    cluster = clone(cluster) 
     1441    prune(cluster, level, height, condition) 
     1442    return cluster 
     1443     
     1444     
     1445def prune(cluster, level=None, height=None, condition=None): 
     1446    """ Prune the clustering instance ``cluster`` in place. 
    13541447     
    13551448    :param cluster: Cluster to prune. 
     
    13731466     
    13741467    level_check = height_check = condition_check = lambda cl: False 
    1375     cluster_depth = cluster_depths(root_cluster) 
     1468    cluster_depth = cluster_depths(cluster) 
    13761469     
    13771470    if level is not None: 
    1378         level_check = lambda cl: cluster_depth[cl] > level 
     1471        level_check = lambda cl: cluster_depth[cl] >= level 
    13791472         
    13801473    if height is not None: 
    1381         height_check = lambda cl: cl.height < height 
     1474        height_check = lambda cl: cl.height <= height 
    13821475 
    13831476    if condition is not None: 
     
    13901483                                            condition_check]]) 
    13911484         
    1392     for cluster in preorder(root_cluster): 
     1485    for cluster in preorder(cluster): 
    13931486        if cluster not in pruned_set: 
    13941487            if check_all(cluster): 
     
    13991492     
    14001493     
    1401 def cluster_depths(root_cluster): 
     1494def cluster_depths(cluster): 
    14021495    """ Return a dictionary mapping :class:`HierarchicalCluster` instances to 
    1403     their depths in the `root_cluster` hierarchy. 
     1496    their depths in the `cluster` hierarchy. 
     1497     
     1498    :param cluster: Root cluster 
     1499    :type cluster: :class:`HierarchicalCluster` 
     1500     
     1501    :rtype: class:`dict` 
    14041502     
    14051503    """ 
    14061504    depths = {} 
    1407     depths[root_cluster] = 0 
    1408     for cluster in preorder(root_cluster): 
     1505    depths[cluster] = 0 
     1506    for cluster in preorder(cluster): 
    14091507        cl_depth = depths[cluster] 
    14101508        if cluster.branches: 
     
    14251523    :type distance_constructor: :class:`Orange.distance.instances.ExampleDistConstructor` 
    14261524     
     1525    :param progress_callback: A function (taking one argument) to use for 
     1526        reporting the on the progress. 
     1527    :type progress_callback: function 
     1528     
     1529    :rtype: :class:`Orange.core.SymMatrix` 
     1530     
    14271531    """ 
    14281532    matrix = orange.SymMatrix(len(data)) 
     
    14301534     
    14311535    iter_count = matrix.dim * (matrix.dim - 1) / 2 
    1432     milestones = progressBarMilestones(iter_count, 100) 
     1536    milestones = progress_bar_milestones(iter_count, 100) 
    14331537     
    14341538    for count, ((i, ex1), (j, ex2)) in enumerate(_pairs(enumerate(data))): 
     
    14461550    :param data: A data table 
    14471551    :type data: :class:`Orange.data.Table` 
     1552     
    14481553    :param distance: a function taking two lists and returning the distance. 
    14491554    :type distance: function 
    1450       
     1555     
     1556    :param progress_callback: A function (taking one argument) to use for 
     1557        reporting the on the progress. 
     1558    :type progress_callback: function 
     1559     
     1560    :rtype: :class:`Orange.core.SymMatrix` 
     1561     
    14511562    """ 
    14521563    attributes = data.domain.attributes 
    14531564    matrix = orange.SymMatrix(len(attributes)) 
    14541565    iter_count = matrix.dim * (matrix.dim - 1) / 2 
    1455     milestones = progressBarMilestones(iter_count, 100) 
     1566    milestones = progress_bar_milestones(iter_count, 100) 
    14561567     
    14571568    for count, ((i, a1), (j, a2)) in enumerate(_pairs(enumerate(attributes))): 
     
    14731584     
    14741585     
    1475 def joining_cluster(root_cluster, item1, item2): 
     1586def joining_cluster(cluster, item1, item2): 
    14761587    """ Return the cluster where `item1` and `item2` are first joined 
    14771588     
    1478     :param root_cluster: Clustering. 
    1479     :type root_cluster: :class:`HierarchicalCluster` 
    1480     :param item1: An element of `root_cluster.mapping` or `root_cluster.mapping.objects` 
    1481     :param item2: An element of `root_cluster.mapping` or `root_cluster.mapping.objects` 
    1482      
    1483     """ 
    1484     cluster = root_cluster 
     1589    :param cluster: Clustering. 
     1590    :type cluster: :class:`HierarchicalCluster` 
     1591    :param item1: An element of `cluster.mapping` or `cluster.mapping.objects` 
     1592    :param item2: An element of `cluster.mapping` or `cluster.mapping.objects` 
     1593     
     1594    :rtype: :class:`HierarchicalCluster` 
     1595     
     1596    """ 
    14851597    while True: 
    14861598        if cluster.branches: 
     
    14951607         
    14961608 
    1497 def cophenetic_distances(root_cluster): 
     1609def cophenetic_distances(cluster): 
    14981610    """ Return the cophenetic distance matrix between items in clustering. 
    14991611    Cophenetic distance is defined as the height of the cluster where the  
    15001612    two items are first joined. 
    15011613     
    1502     :param root_cluster: Clustering. 
    1503     :type root_cluster: :class:`HierarchicalCluster` 
    1504       
    1505     """ 
    1506  
    1507     mapping = root_cluster.mapping   
     1614    :param cluster: Clustering. 
     1615    :type cluster: :class:`HierarchicalCluster` 
     1616     
     1617    :rtype: :class:`Orange.core.SymMatrix` 
     1618     
     1619    """ 
     1620 
     1621    mapping = cluster.mapping   
    15081622    matrix = Orange.core.SymMatrix(len(mapping)) 
    1509     for cluster in postorder(root_cluster): 
     1623    for cluster in postorder(cluster): 
    15101624        if cluster.branches: 
    15111625            for branch1, branch2 in _pairs(cluster.branches): 
     
    15191633     
    15201634    return matrix 
    1521      
    1522 def cophenetic_correlation(root_cluster, matrix): 
     1635 
     1636     
     1637def cophenetic_correlation(cluster, matrix): 
    15231638    """ Return the `cophenetic correlation coefficient 
    15241639    <http://en.wikipedia.org/wiki/Cophenetic_correlation>`_ of the given 
    15251640    clustering. 
    15261641     
    1527     :param root_cluster: Clustering. 
    1528     :type root_cluster: :class:`HierarchicalCluster` 
    1529      
    1530     :param matrix: The distance matrix from which the `root_cluster` was 
     1642    :param cluster: Clustering. 
     1643    :type cluster: :class:`HierarchicalCluster` 
     1644     
     1645    :param matrix: The distance matrix from which the `cluster` was 
    15311646        derived. 
    1532       
     1647     
     1648    :rtype: :class:`float` 
     1649     
    15331650    """ 
    15341651    import numpy 
    1535     cophenetic = cophenetic_distances(root_cluster) 
     1652    cophenetic = cophenetic_distances(cluster) 
    15361653    cophenetic = [list(row) for row in cophenetic] 
    15371654    original = [list(row) for row in matrix] 
  • orange/Orange/misc/__init__.py

    r8762 r9050  
    5555 
    5656 
    57 def demangleExamples(x): 
     57def demangle_examples(x): 
    5858    if type(x)==types.TupleType: 
    5959        return x 
     
    6363 
    6464def frange(*argw): 
     65    """ Like builtin `range` but works with floats 
     66    """ 
    6567    start, stop, step = 0.0, 1.0, 0.1 
    6668    if len(argw)==1: 
     
    8688verbose = 0 
    8789 
    88 def printVerbose(text, *verb): 
     90def print_verbose(text, *verb): 
    8991    if len(verb) and verb[0] or verbose: 
    9092        print text 
    9193 
     94__doc__ += """\ 
     95------------------ 
     96Reporting progress 
     97------------------ 
     98 
     99.. autoclass:: Orange.misc.ConsoleProgressBar 
     100    :members: 
     101 
     102""" 
     103 
    92104class ConsoleProgressBar(object): 
    93     def __init__(self, title="", charwidth=40, step=1, output=sys.stderr): 
     105    """ A class to for printing progress bar reports in the console. 
     106     
     107    Example :: 
     108     
     109        >>> import sys, time 
     110        >>> progress = ConsoleProgressBar("Example", output=sys.stdout) 
     111        >>> for i in range(100): 
     112        ...    progress.advance() 
     113        ...    # Or 
     114        ...    progress.set_state(i) 
     115        ...    time.sleep(0.01) 
     116        ... 
     117        ... 
     118        Example ===================================>100% 
     119         
     120    """ 
     121    def __init__(self, title="", charwidth=40, step=1, output=None): 
     122        """ Initialize the progress bar. 
     123         
     124        :param title: The title for the progress bar. 
     125        :type title: str 
     126        :param charwidth: The maximum progress bar width in characters. 
     127         
     128            .. todo:: Get the console width from the ``output`` if the 
     129                information can be retrieved.  
     130                 
     131        :type charwidth: int 
     132        :param step: A default step used if ``advance`` is called without 
     133            any  arguments 
     134         
     135        :type step: int 
     136        :param output: The output file. If None (default) then ``sys.stderr`` 
     137            is used. 
     138             
     139        :type output: An file like object to print the progress report to. 
     140          
     141        """ 
    94142        self.title = title + " " 
    95143        self.charwidth = charwidth 
     
    97145        self.currstring = "" 
    98146        self.state = 0 
     147        if output is None: 
     148            output = sys.stderr 
    99149        self.output = output 
    100150 
    101151    def clear(self, i=-1): 
     152        """ Clear the current progress line indicator string. 
     153        """ 
    102154        try: 
    103155            if hasattr(self.output, "isatty") and self.output.isatty(): 
     
    109161 
    110162    def getstring(self): 
     163        """ Return the progress indicator string. 
     164        """ 
    111165        progchar = int(round(float(self.state) * (self.charwidth - 5) / 100.0)) 
    112166        return self.title + "=" * (progchar) + ">" + " " * (self.charwidth\ 
     
    114168 
    115169    def printline(self, string): 
     170        """ Print the ``string`` to the output file. 
     171        """ 
    116172        try: 
    117173            self.clear() 
     
    123179 
    124180    def __call__(self, newstate=None): 
    125         if newstate == None: 
    126             newstate = self.state + self.step 
     181        """ Set the ``newstate`` as the current state of the progress bar. 
     182        ``newstate`` must be in the interval [0, 100]. 
     183         
     184        .. note:: ``set_state`` is the prefered way to set a new steate.  
     185         
     186        :param newstate: The new state of the progress bar. 
     187        :type newstate: float 
     188          
     189        """ 
     190        if newstate is None: 
     191            self.advance() 
     192        else: 
     193            self.set_state(newstate) 
     194             
     195    def set_state(self, newstate): 
     196        """ Set the ``newstate`` as the current state of the progress bar. 
     197        ``newstate`` must be in the interval [0, 100].  
     198         
     199        :param newstate: The new state of the progress bar. 
     200        :type newstate: float 
     201         
     202        """ 
    127203        if int(newstate) != int(self.state): 
    128204            self.state = newstate 
     
    130206        else: 
    131207            self.state = newstate 
     208             
     209    def advance(self, step=None): 
     210        """ Advance the current state by ``step``. If ``step`` is None use 
     211        the default step as set at class initialization. 
     212           
     213        """ 
     214        if step is None: 
     215            step = self.step 
     216             
     217        newstate = self.state + step 
     218        self.set_state(newstate) 
    132219 
    133220    def finish(self): 
     221        """ Finish the progress bar (i.e. set the state to 100 and 
     222        print the final newline to the ``output`` file). 
     223        """ 
    134224        self.__call__(100) 
    135225        self.output.write("\n") 
    136226 
    137 def progressBarMilestones(count, iterations=100): 
     227def progress_bar_milestones(count, iterations=100): 
    138228    return set([int(i*count/float(iterations)) for i in range(iterations)]) 
    139229 
     
    174264from contextlib import contextmanager 
    175265 
     266 
    176267@contextmanager 
    177268def member_set(obj, name, val): 
     
    184275    setattr(obj, name, old_val) 
    185276     
    186  
     277     
    187278class recursion_limit(object): 
    188279    """ A context manager that sets a new recursion limit.  
     
    201292 
    202293__doc__ += """\ 
    203 ============================= 
     294----------------------------- 
    204295Deprecation utility functions 
    205 ============================= 
     296----------------------------- 
    206297 
    207298.. autofunction:: Orange.misc.deprecation_warning 
     
    212303 
    213304.. autofunction:: Orange.misc.deprecated_attribute 
     305 
     306.. autofunction:: Orange.misc.deprecated_function_name  
    214307 
    215308""" 
     
    404497    return prop  
    405498 
     499 
     500def deprecated_function_name(func): 
     501    """ Return a wrapped function that raises an deprecation warning when 
     502    called. This should be used for deprecation of module level function names.  
     503     
     504    Example :: 
     505     
     506        >>> def func_a(arg): 
     507        ...    print "This is func_a  (used to be named funcA) called with", arg 
     508        ... 
     509        ... 
     510        >>> funcA = deprecated_function_name(func_a) 
     511        >>> funcA(None) 
     512           
     513     
     514    .. note:: This decorator does nothing and if \ 
     515        :obj:`Orange.misc.environ.orange_no_deprecated_members` environment \ 
     516        variable is set to `True`. 
     517         
     518    """ 
     519    if environ.orange_no_deprecated_members: 
     520        return func 
     521     
     522    @wraps(func) 
     523    def wrapped(*args, **kwargs): 
     524        warnings.warn("Deprecated function name. Use %r instead!" % func.__name__, 
     525                      DeprecationWarning, stacklevel=2) 
     526        return func(*args, **kwargs) 
     527    return wrapped 
     528     
     529 
    406530""" 
    407531Some utility functions common to Orange classes. 
     
    447571 
    448572 
    449      
     573demangleExamples = deprecated_function_name(demangle_examples) 
     574progressBarMilestones = deprecated_function_name(progress_bar_milestones) 
     575printVerbose = deprecated_function_name(print_verbose) 
Note: See TracChangeset for help on using the changeset viewer.