Merge branch 'release-1.2.0' into develop

Author: exhuma

.gitignore

@@ -1,6 +1,8 @@
 *.pyc
+/*.egg-info
 /MANIFEST
 /build
 /dist
+/docs/_build
 /env
 /env3

CHANGELOG

@@ -1,4 +1,5 @@
 1.2.0
+   - Python 3 support
    - Split up one big file into smaller more logical sub-modules
 
 1.1.1b3

INSTALL

@@ -1,44 +1,27 @@
 INSTALLATION
 ============
 
-Linux
------
+Simply run::
 
-RPM-Installation
-~~~~~~~~~~~~~~~~
+    pip install cluster
 
-I'm not familiar with RPM-distributions but as far as I know it should be
-something like::
+Or, if you run it in a virtualenv:
 
-   rpm -i <filename.rpm>
+    /path/to/your/env/bin/pip install cluster
 
-RPM-source Installation
-~~~~~~~~~~~~~~~~~~~~~~~
 
-This is something I don't know. If somebody can enlighten me, please do!
+Source installation
+~~~~~~~~~~~~~~~~~~~
 
-Binary/Source installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Untar the archive::
 
-Untar the package with you favourite archive tool. On the console it will be
-something along the lines::
-
-   tar xzf <filename.tar.gz>
+   tar xf <filename.tar.gz>
 
 Next, go to the folder just created. It will have the same name as the package
-(for example "cluster-1.0.0b1") and run::
-
-   python setup.py install
-
-For this step you need root-priviledges
-
-Windows
--------
+(for example "cluster-1.2.0") and run::
 
-Execute the executable file and follow the instructions displayed. Default
-values will be fine in most cases.
+    python setup.py install
 
-MacOS-X
--------
+This will require superuser privileges unless you install it in a virtual environment::
 
-Simply follow the same instructions as with the Linux-Source installation.
+    /path/to/your/env/bin/python setup.py install

README

@@ -9,13 +9,17 @@ between two of those objects. For simple datatypes, like integers, this can be
 as simple as a subtraction, but more complex calculations are possible. Right
 now, it is possible to generate the clusters using a hierarchical clustering
 and the popular K-Means algorithm. For the hierarchical algorithm there are
-different "linkage" (single, complete, average and uclus) methods available. I
-plan to implement other algoithms as well on an
-"as-needed" or "as-I-have-time" basis.
+different "linkage" (single, complete, average and uclus) methods available.
 
 Algorithms are based on the document found at
 http://www.elet.polimi.it/upload/matteucc/Clustering/tutorial_html/
 
+.. note::
+    The above site is no longer avaialble, but you can still view it in the
+    internet archive at:
+    https://web.archive.org/web/20070912040206/http://home.dei.polimi.it//matteucc/Clustering/tutorial_html/
+
+
 USAGE
 =====
 

cluster/cluster.py

@@ -15,6 +15,8 @@
 # Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 #
 
+from __future__ import print_function
+
 
 class Cluster(object):
     """
@@ -34,16 +36,13 @@ def __init__(self, level, *args):
         """
         Constructor
 
-        PARAMETERS
-            level - The level of this cluster. This is used in hierarchical
-                    clustering to retrieve a specific set of clusters. The
-                    higher the level, the smaller the count of clusters
-                    returned. The level depends on the difference function
-                    used.
-            *args - every additional argument passed following the level value
-                    will get added as item to the cluster. You could also pass
-                    a list as second parameter to initialise the cluster with
-                    that list as content
+        :param level: The level of this cluster. This is used in hierarchical
+            clustering to retrieve a specific set of clusters. The higher the
+            level, the smaller the count of clusters returned. The level depends
+            on the difference function used.
+        :param *args: every additional argument passed following the level value
+            will get added as item to the cluster. You could also pass a list as
+            second parameter to initialise the cluster with that list as content
         """
         self.__level = level
         if len(args) == 0:
@@ -55,18 +54,16 @@ def append(self, item):
         """
         Appends a new item to the cluster
 
-        PARAMETERS
-            item  -  The item that is to be appended
+        :param item: The item that is to be appended.
         """
         self.__items.append(item)
 
     def items(self, new_items=None):
         """
         Sets or gets the items of the cluster
 
-        PARAMETERS
-            new_items (optional) - if set, the items of the cluster will be
-                                  replaced with that argument.
+        :param new_items: if set, the items of the cluster will be replaced with
+            that argument.
         """
         if new_items is None:
             return self.__items
@@ -80,8 +77,7 @@ def fullyflatten(self, *args):
         some items of the cluster are clusters in their own right and you only
         want the items.
 
-        PARAMETERS
-            *args - only used for recursion.
+        :param *args: only used for recursion.
         """
         flattened_items = []
         if len(args) == 0:
@@ -99,39 +95,41 @@ def fullyflatten(self, *args):
 
     def level(self):
         """
-        Returns the level associated with this cluster
+        Returns the level associated with this cluster.
         """
         return self.__level
 
     def display(self, depth=0):
         """
-        Pretty-prints this cluster. Useful for debuging
+        Pretty-prints this cluster. Useful for debuging.
         """
-        print depth * "    " + "[level %s]" % self.__level
+        print(depth * "    " + "[level %s]" % self.__level)
         for item in self.__items:
             if isinstance(item, Cluster):
                 item.display(depth + 1)
             else:
-                print depth * "    " + "%s" % item
+                print(depth * "    " + "%s" % item)
 
     def topology(self):
         """
         Returns the structure (topology) of the cluster as tuples.
 
-        Output from cl.data:
-             [<[email protected](['CVS',
-             <[email protected](['34.xls',
-             <[email protected]([<[email protected](['0.txt',
-             <[email protected](['ChangeLog', 'ChangeLog.txt'])>])>,
-             <[email protected](['20060730.py',
-             <[email protected](['.cvsignore',
-             <[email protected](['About.py', <[email protected](['.idlerc',
-             '.pylint.d'])>])>])>])>])>])>])>]
+        Output from cl.data::
+
+                [<[email protected](['CVS',
+                 <[email protected](['34.xls',
+                 <[email protected]([<[email protected](['0.txt',
+                 <[email protected](['ChangeLog', 'ChangeLog.txt'])>])>,
+                 <[email protected](['20060730.py',
+                 <[email protected](['.cvsignore',
+                 <[email protected](['About.py', <[email protected](['.idlerc',
+                 '.pylint.d'])>])>])>])>])>])>])>]
+
+        Corresponding output from cl.topo()::
 
-        Corresponding output from cl.topo():
-             ('CVS', ('34.xls', (('0.txt', ('ChangeLog', 'ChangeLog.txt')),
-             ('20060730.py', ('.cvsignore', ('About.py',
-             ('.idlerc', '.pylint.d')))))))
+                ('CVS', ('34.xls', (('0.txt', ('ChangeLog', 'ChangeLog.txt')),
+                ('20060730.py', ('.cvsignore', ('About.py',
+                ('.idlerc', '.pylint.d')))))))
         """
 
         left = self.__items[0]
@@ -157,10 +155,9 @@ def getlevel(self, threshold):
         receive and the higher you set it, you will receive less but bigger
         clusters.
 
-        PARAMETERS
-            threshold - The level threshold
+        :param threshold: The level threshold:
 
-        NOTE
+        .. note::
             It is debatable whether the value passed into this method should
             really be as strongly linked to the real cluster-levels as it is
             right now. The end-user will not know the range of this value

cluster/matrix.py

@@ -1,3 +1,20 @@
+#
+# This is part of "python-cluster". A library to group similar items together.
+# Copyright (C) 2006    Michel Albert
+#
+# This library is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as published by the
+# Free Software Foundation; either version 2.1 of the License, or (at your
+# option) any later version.
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+# for more details.
+# You should have received a copy of the GNU Lesser General Public License
+# along with this library; if not, write to the Free Software Foundation,
+# Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+#
+
 
 import logging
 from multiprocessing import Process, Queue, current_process
@@ -7,35 +24,35 @@
 
 
 class Matrix(object):
-    """Object representation of the item-item matrix
+    """
+    Object representation of the item-item matrix.
     """
 
     def __init__(self, data, combinfunc, symmetric=False, diagonal=None):
-        """Takes a list of data and generates a 2D-matrix using the supplied
+        """
+        Takes a list of data and generates a 2D-matrix using the supplied
         combination function to calculate the values.
 
-        PARAMETERS
-            data        - the list of items
-            combinfunc  - the function that is used to calculate teh value in a
-                          cell.  It has to cope with two arguments.
-            symmetric   - Whether it will be a symmetric matrix along the diagonal.
-                          For example, if the list contains integers, and the
-                          combination function is abs(x-y), then the matrix will
-                          be symmetric.
-                          Default: False
-            diagonal    - The value to be put into the diagonal. For some
-                          functions, the diagonal will stay constant. An example
-                          could be the function "x-y". Then each diagonal cell
-                          will be "0".  If this value is set to None, then the
-                          diagonal will be calculated.  Default: None
+        :param data: the list of items.
+        :param combinfunc: the function that is used to calculate teh value in a
+            cell. It has to cope with two arguments.
+        :param symmetric: Whether it will be a symmetric matrix along the
+            diagonal.  For example, if the list contains integers, and the
+            combination function is ``abs(x-y)``, then the matrix will be
+            symmetric.
+        :param diagonal: The value to be put into the diagonal. For some
+            functions, the diagonal will stay constant. An example could be the
+            function ``x-y``. Then each diagonal cell will be ``0``.  If this
+            value is set to None, then the diagonal will be calculated.
         """
         self.data = data
         self.combinfunc = combinfunc
         self.symmetric = symmetric
         self.diagonal = diagonal
 
     def worker(self):
-        """Multiprocessing task function run by worker processes
+        """
+        Multiprocessing task function run by worker processes
         """
         tasks_completed = 0
         for task in iter(self.task_queue.get, 'STOP'):
@@ -50,14 +67,13 @@ def worker(self):
                     tasks_completed)
 
     def genmatrix(self, num_processes=1):
-        """Actually generate the matrix
-
-        PARAMETERS
-            num_processes
-                        - If you want to use multiprocessing to split up the work
-                          and run combinfunc() in parallel, specify num_processes
-                          > 1 and this number of workers will be spun up, the work
-                          split up amongst them evenly. Default: 1
+        """
+        Actually generate the matrix
+
+        :param num_processes: If you want to use multiprocessing to split up the
+            work and run ``combinfunc()`` in parallel, specify
+            ``num_processes > 1`` and this number of workers will be spun up,
+            the work is split up amongst them evenly.
         """
         use_multiprocessing = num_processes > 1
         if use_multiprocessing:
@@ -136,11 +152,8 @@ def genmatrix(self, num_processes=1):
 
     def __str__(self):
         """
-        Prints out a 2-dimensional list of data cleanly.
-        This is useful for debugging.
-
-        PARAMETERS
-            data  -  the 2D-list to display
+        Returns a 2-dimensional list of data as text-string which can be
+        displayed to the user.
         """
         # determine maximum length
         maxlen = 0

cluster/method/base.py

@@ -19,33 +19,27 @@
 class BaseClusterMethod(object):
     """
     The base class of all clustering methods.
-    """
-
-    def __init__(self, input, distance_function):
-        """
-        Constructs the object and starts clustering
 
-        PARAMETERS
-            input             - a list of objects
-            distance_function - a function returning the distance - or
-                                opposite of similarity ( distance =
-                                -similarity ) - of two items from the input.
-                                In other words, the closer the two items are
-                                related, the smaller this value needs to be.
-                                With 0 meaning they are exactly the same.
+    :param input: a list of objects
+    :distance_function: a function returning the distance - or opposite of
+        similarity ``(distance = -similarity)`` - of two items from the input.
+        In other words, the closer the two items are related, the smaller this
+        value needs to be.  With 0 meaning they are exactly the same.
 
-        NOTES
-            The distance function should always return the absolute distance
-            between two given items of the list. Say,
+    .. note::
+        The distance function should always return the absolute distance between
+        two given items of the list. Say::
 
             distance(input[1], input[4]) = distance(input[4], input[1])
 
-            This is very important for the clustering algorithm to work!
-            Naturally, the data returned by the distance function MUST be a
-            comparable datatype, so you can perform arithmetic comparisons on
-            them (< or >)! The simplest examples would be floats or ints. But
-            as long as they are comparable, it's ok.
-        """
+        This is very important for the clustering algorithm to work!  Naturally,
+        the data returned by the distance function MUST be a comparable
+        datatype, so you can perform arithmetic comparisons on them (``<`` or
+        ``>``)! The simplest examples would be floats or ints. But as long as
+        they are comparable, it's ok.
+    """
+
+    def __init__(self, input, distance_function):
         self.distance = distance_function
         self._input = input    # the original input
         self._data = input[:]  # clone the input so we can work with it
@@ -55,7 +49,7 @@ def topo(self):
         """
         Returns the structure (topology) of the cluster.
 
-        See Cluster.topology() for information.
+        See :py:meth:`~cluster.cluster.Cluster.topology` for more information.
         """
         return self.data[0].topology()