Merge pull request #50 from lucasimi/feature/alignement

Feature/alignement

Author: lucasimi

src/tdamapper/clustering.py

@@ -1,7 +1,6 @@
+'''A module containing the logic related to clustering for the Mapper algorithm.'''
 import logging
 
-import numpy as np
-
 from tdamapper.core import mapper_connected_components
 from tdamapper.cover import TrivialCover
 
@@ -14,11 +13,10 @@
     level = logging.INFO)
 
 
-def euclidean(x, y):
-    return np.linalg.norm(x - y)
-
-
 class TrivialClustering:
+    '''
+    A clustering algorithm that returns a single cluster.
+    '''
 
     def __init__(self):
         self.labels_ = None
@@ -28,7 +26,17 @@ def fit(self, X, y=None):
         return self
 
 
-class PermissiveClustering:
+class FailSafeClustering:
+    '''
+    A delegating clustering algorithm that prevents failure.
+    When clustering fails, instead of throwing an exception,
+    a single cluster, containing all points, is returned.
+
+    :param clustering: A clustering algorithm to delegate to.
+    :type clustering: Anything compatible with a `sklearn.cluster` class.
+    :param verbose: Set to `True` to log exceptions.
+    :type verbose: `bool`
+    '''
 
     def __init__(self, clustering, verbose=True):
         self.__clustering = clustering
@@ -47,6 +55,19 @@ def fit(self, X, y=None):
 
 
 class MapperClustering:
+    '''
+    A clustering algorithm based on the Mapper graph.
+    The Mapper algorithm returns a graph where each point is eventually contained 
+    in multiple nodes. In this case all those nodes are connected in the Mapper graph,
+    therefore they share the same connected component. For this reason the notion of
+    connected component is well-defined for any point of the dataset. This class 
+    clusters point according to their connected component in the Mapper graph.
+
+    :type cover: A cover algorithm.
+    :type cover: Anything compatible with a `tdamapper.cover` class.
+    :param clustering: A clustering algorithm.
+    :type clustering: Anything compatible with a `sklearn.cluster` class.
+    '''
 
     def __init__(self, cover=None, clustering=None):
         self.cover = cover

src/tdamapper/core.py

@@ -1,3 +1,5 @@
+'''A module containing the main implementation logic for the Mapper algorithm.'''
+
 import networkx as nx
 
 from tdamapper.utils.unionfind import UnionFind
@@ -11,18 +13,18 @@ def mapper_labels(X, y, cover, clustering):
     '''
     Computes the open cover, then perform local clustering on each open set from the cover.
 
-    :param X: A dataset
-    :type X: numpy.ndarray or list-like
-    :param y: lens values
-    :type y: numpy.ndarray or list-like
-    :param cover: A cover algorithm
-    :type cover: A class from tdamapper.cover
-    :param clustering: A clustering algorithm
-    :type clustering: A class from tdamapper.clustering or a class from sklearn.cluster
+    :param X: A dataset.
+    :type X: `numpy.ndarray` or list-like.
+    :param y: Lens values.
+    :type y: `numpy.ndarray` or list-like.
+    :param cover: A cover algorithm.
+    :type cover: A class from `tdamapper.cover`.
+    :param clustering: A clustering algorithm.
+    :type clustering: A class from `tdamapper.clustering` or a class from `sklearn.cluster`.
     :return: A list where each item is a sorted list of ints with no duplicate.
-    The list at position i contains the cluster labels to which the point at position i in X 
-    belongs to. If i < j, the labels at position i are strictly less then those at position j.
-    :rtype: list[list[int]]
+    The list at position `i` contains the cluster labels to which the point at position `i` in `X`
+    belongs to. If `i < j`, the labels at position `i` are strictly less then those at position `j`.
+    :rtype: `list[list[int]]`.
     '''
     itm_lbls = [[] for _ in X]
     max_lbl = 0
@@ -39,12 +41,30 @@ def mapper_labels(X, y, cover, clustering):
 
 
 def mapper_connected_components(X, y, cover, clustering):
+    ''' 
+    Computes the connected components of the Mapper graph.
+    The algorithm computes the connected components using a union-find data structure.
+    This approach should be faster than computing the Mapper graph by first calling
+    `tdamapper.core.mapper_graph` and then calling `networkx.connected_components` on it.
+
+    :param X: A dataset.
+    :type X: `numpy.ndarray` or list-like.
+    :param y: Lens values.
+    :type y: `numpy.ndarray` or list-like.
+    :param cover: A cover algorithm.
+    :type cover: A class from `tdamapper.cover`.
+    :param clustering: A clustering algorithm.
+    :type clustering: A class from `tdamapper.clustering` or a class from `sklearn.cluster`.
+    :return: A list of labels, where the value at position `i` identifies
+    the connected component of the point `X[i]`.
+    :rtype: `list[int]`.
+    '''
     itm_lbls = mapper_labels(X, y, cover, clustering)
     label_values = set()
     for lbls in itm_lbls:
         label_values.update(lbls)
     uf = UnionFind(label_values)
-    labels = []
+    labels = [-1 for _ in X]
     for lbls in itm_lbls:
         len_lbls = len(lbls)
         # noise points
@@ -61,18 +81,18 @@ def mapper_connected_components(X, y, cover, clustering):
 
 def mapper_graph(X, y, cover, clustering):
     ''' 
-    Computes the Mapper graph
-
-    :param X: A dataset
-    :type X: numpy.ndarray or list-like
-    :param y: Lens values
-    :type y: numpy.ndarray or list-like
-    :param cover: A cover algorithm
-    :type cover: A class from tdamapper.cover
-    :param clustering: A clustering algorithm
-    :type clustering: A class from tdamapper.clustering or a class from sklearn.cluster
-    :return: The Mapper graph
-    :rtype: networkx.Graph
+    Computes the Mapper graph.
+
+    :param X: A dataset.
+    :type X: `numpy.ndarray` or list-like.
+    :param y: Lens values.
+    :type y: `numpy.ndarray` or list-like.
+    :param cover: A cover algorithm.
+    :type cover: A class from `tdamapper.cover`.
+    :param clustering: A clustering algorithm.
+    :type clustering: A class from `tdamapper.clustering` or a class from `sklearn.cluster`.
+    :return: The Mapper graph.
+    :rtype: `networkx.Graph`.
     '''
     itm_lbls = mapper_labels(X, y, cover, clustering)
     graph = nx.Graph()
@@ -95,6 +115,18 @@ def mapper_graph(X, y, cover, clustering):
 
 
 def aggregate_graph(y, graph, agg):
+    ''' 
+    Computes an aggregation on the nodes of a graph.
+
+    :param y: A dataset.
+    :type y: `numpy.ndarray` or list-like.
+    :param graph: A graph.
+    :type graph: `networkx.Graph`.
+    :param agg: An aggregation function.
+    :type agg: Callable.
+    :return: A dict of values, where each node is mapped to its aggregation.
+    :rtype: `dict`.
+    '''
     agg_values = {}
     nodes = graph.nodes()
     for node_id in nodes:
@@ -108,10 +140,10 @@ class MapperAlgorithm:
     ''' 
     Main class for performing the Mapper Algorithm.
 
-    :param cover: A cover algorithm
-    :type cover: A class from tdamapper.cover
-    :param clustering: A clustering algorithm
-    :type clustering: A class from tdamapper.clustering or a class from sklearn.cluster
+    :param cover: A cover algorithm.
+    :type cover: A class from `tdamapper.cover`.
+    :param clustering: A clustering algorithm.
+    :type clustering: A class from `tdamapper.clustering` or a class from `sklearn.cluster`.
     '''
 
     def __init__(self, cover, clustering):
@@ -123,24 +155,24 @@ def fit(self, X, y=None):
         ''' 
         Computes the Mapper Graph
 
-        :param X: A dataset
-        :type X: numpy.ndarray or list-like
-        :param y: Lens values
-        :type y: numpy.ndarray or list-like
-        :return: self
+        :param X: A dataset.
+        :type X: `numpy.ndarray` or list-like.
+        :param y: Lens values.
+        :type y: `numpy.ndarray` or list-like.
+        :return: `self`.
         '''
         self.graph_ = self.fit_transform(X, y)
         return self
 
     def fit_transform(self, X, y):
         ''' 
-        Computes the Mapper Graph
-
-        :param X: A dataset
-        :type X: numpy.ndarray or list-like
-        :param y: Lens values
-        :type y: numpy.ndarray or list-like
-        :return: The Mapper Graph
-        :rtype: networkx.Graph
+        Computes the Mapper Graph.
+
+        :param X: A dataset.
+        :type X: `numpy.ndarray` or list-like.
+        :param y: Lens values.
+        :type y: `numpy.ndarray` or list-like.
+        :return: The Mapper graph.
+        :rtype: `networkx.Graph`
         '''
         return mapper_graph(X, y, self.__cover, self.__clustering)

src/tdamapper/cover.py

@@ -1,21 +1,28 @@
+'''A module containing the logic for building open covers for the Mapper algorithm.'''
 import numpy as np
 
 from tdamapper.utils.vptree_flat import VPTree
 
 
-class __ProximityNetCover:
+class ProximityNetCover:
+    '''
+    This class serves as a blueprint for proximity-based cover algorithm
+    and implements proximity-net in the `ProximityNetCover.apply` method.
+    Subclasses are expected to override the methods `ProximityNetCover.fit` 
+    and `ProximityNetCover.search`.
+    '''
 
     def __init__(self):
         pass
 
     def apply(self, X):
         '''
-        Compute the proximity-net for a given open cover.
+        Compute proximity-net for a given open cover.
+        Returns a generator where each item is a subset of ids
+        of points from `X`.
 
-        :param X: A dataset
-        :type X: numpy.ndarray or list-like
-        :param proximity: A proximity function
-        :type proximity: A class from tdamapper.proximity
+        :param X: A dataset.
+        :type X: `numpy.ndarray` or list-like.
         '''
         covered_ids = set()
         self.fit(X)
@@ -33,16 +40,16 @@ def search(self, x):
         return []
 
 
-class BallCover(__ProximityNetCover):
+class BallCover(ProximityNetCover):
     '''
-    Create an open cover made of overlapping open balls of fixed radius.
+    Creates an open cover made of overlapping open balls of fixed radius.
     This class implements the Ball Proximity function: after calling fit on X, 
-    the search method returns all the points within a ball centered in the target point.
+    the `BallCover.search` method returns all the points within a ball centered in the target point.
 
     :param radius: The radius of open balls
-    :type radius: float
-    :param metric: The metric used to define open balls
-    :type metric: function
+    :type radius: float.
+    :param metric: The metric used to define open balls.
+    :type metric: Callable.
     '''
 
     def __init__(self, radius, metric):
@@ -58,22 +65,22 @@ def fit(self, X):
         return self
 
     def search(self, x):
-        if self.__vptree:
-            neighs = self.__vptree.ball_search((-1, x), self.__radius)
-            return [x for (x, _) in neighs]
-        return []
+        if self.__vptree is None:
+            return []
+        neighs = self.__vptree.ball_search((-1, x), self.__radius)
+        return [x for (x, _) in neighs]
 
 
-class KNNCover(__ProximityNetCover):
+class KNNCover(ProximityNetCover):
     '''
-    Create an open cover where each open set containes a fixed number of neighbors, using KNN.
+    Creates an open cover where each open set containes a fixed number of neighbors, using KNN.
     This class implements the KNN Proximity function: after calling fit on X,
-    the search method returns the k nearest points to the target point.
+    the `KNNCover.search` method returns the k nearest points to the target point.
 
-    :param neighbors: The number of neighbors
-    :type neighbors: int
-    :param metric: The metric used to search neighbors
-    :type metric: function
+    :param neighbors: The number of neighbors.
+    :type neighbors: int.
+    :param metric: The metric used to search neighbors.
+    :type metric: function.
     '''
 
     def __init__(self, neighbors, metric):
@@ -94,18 +101,18 @@ def search(self, x):
         return [x for (x, _) in neighs]
 
 
-class CubicalCover(__ProximityNetCover):
+class CubicalCover(ProximityNetCover):
     '''
-    Create an open cover of hypercubes of evenly-sized sides and overlap.
+    Creates an open cover of hypercubes of evenly-sized sides and overlap.
     This class implements the Cubical Proximity function: after calling fit on X,
-    the search method returns the hypercube whose center is nearest to
+    the `CubicalCover.search` method returns the hypercube whose center is nearest to
     the target point. Each hypercube is the product of 1-dimensional intervals
     with the same lenght and overlap.
 
-    :param n_intervals: The number of intervals on each dimension
-    :type n_intervals: int
-    :param overlap_frac: The overlap fracion
-    :type overlap_frac: float in (0.0, 1.0)
+    :param n_intervals: The number of intervals on each dimension.
+    :type n_intervals: int.
+    :param overlap_frac: The overlap fraction.
+    :type overlap_frac: float in (0.0, 1.0).
     '''
 
     def __init__(self, n_intervals, overlap_frac):
@@ -159,9 +166,9 @@ def search(self, x):
         return self.__ball_proximity.search(self._phi(x))
 
 
-class TrivialCover(__ProximityNetCover):
+class TrivialCover(ProximityNetCover):
     '''
-    Create an open cover made of a single open set that contains the whole dataset.
+    Creates an open cover made of a single open set that contains the whole dataset.
     '''
 
     def fit(self, X):