Merge pull request #58 from lucasimi/develop

Develop

Author: lucasimi

src/tdamapper/core.py

@@ -21,10 +21,11 @@ def mapper_labels(X, y, cover, clustering):
     :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]]`.
+    :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]]`
     '''
     itm_lbls = [[] for _ in X]
     max_lbl = 0
@@ -43,9 +44,10 @@ 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.
+    
+    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 `mapper_graph` 
+    and then calling `networkx.connected_components` on it.
 
     :param X: A dataset.
     :type X: `numpy.ndarray` or list-like.
@@ -55,9 +57,9 @@ def mapper_connected_components(X, y, cover, clustering):
     :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]`.
+    :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()
@@ -67,12 +69,11 @@ def mapper_connected_components(X, y, cover, clustering):
     labels = [-1 for _ in X]
     for lbls in itm_lbls:
         len_lbls = len(lbls)
+        root = -1
         # noise points
-        if len_lbls == 0:
-            root = -1
-        elif len_lbls == 1:
+        if len_lbls == 1:
             root = uf.find(lbls[0])
-        else:
+        elif len_lbls > 1:
             for first, second in zip(lbls, lbls[1:]):
                 root = uf.union(first, second)
         labels.append(root)
@@ -92,7 +93,7 @@ def mapper_graph(X, y, cover, clustering):
     :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`.
+    :rtype: `networkx.Graph`
     '''
     itm_lbls = mapper_labels(X, y, cover, clustering)
     graph = nx.Graph()
@@ -125,7 +126,7 @@ def aggregate_graph(y, graph, agg):
     :param agg: An aggregation function.
     :type agg: Callable.
     :return: A dict of values, where each node is mapped to its aggregation.
-    :rtype: `dict`.
+    :rtype: `dict`
     '''
     agg_values = {}
     nodes = graph.nodes()
@@ -143,7 +144,8 @@ class MapperAlgorithm:
     :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`.
+    :type clustering: A class from `tdamapper.clustering` 
+        or a class from `sklearn.cluster`
     '''
 
     def __init__(self, cover, clustering):
@@ -153,7 +155,7 @@ def __init__(self, cover, clustering):
 
     def fit(self, X, y=None):
         ''' 
-        Computes the Mapper Graph
+        Computes the Mapper Graph.
 
         :param X: A dataset.
         :type X: `numpy.ndarray` or list-like.

src/tdamapper/cover.py

@@ -1,19 +1,20 @@
 '''A module containing the logic for building open covers for the Mapper algorithm.'''
 import numpy as np
 
-from tdamapper.utils.vptree_flat import VPTree
+from tdamapper.utils.vptree_flat import VPTree as FVPT
+from tdamapper.utils.vptree import VPTree as VPT
 
 
 def proximity_net(X, proximity):
     '''
     Compute proximity-net for a given proximity function.
-    Returns a generator where each item is a subset of ids
-    of points from `X`.
+    
+    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: `tdamapper.cover.Proximity`.
+    :type proximity: `tdamapper.cover.Proximity`
     '''
     covered_ids = set()
     proximity.fit(X)
@@ -27,9 +28,9 @@ def proximity_net(X, proximity):
 
 class Proximity:
     '''
-    This class serves as a blueprint for proximity functions used inside 
-    `tdamapper.cover.proximity_net`. Subclasses are expected to override 
-    the methods `fit` and `search`.
+    This class serves as a blueprint for proximity functions used inside `proximity_net`.
+    
+    Subclasses are expected to override the methods `fit` and `search`.
     '''
 
     def fit(self, X):
@@ -55,25 +56,34 @@ def apply(self, X):
 class BallCover(ProximityNetCover):
     '''
     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 `BallCover.search` method returns all the points within a ball centered in the target point.
+
+    This class implements the Ball Proximity function: after calling `fit`, the `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: Callable.
+    :param flat: Set to True to use flat vptrees.
+    :type flat: `bool`
     '''
 
-    def __init__(self, radius, metric):
+    def __init__(self, radius, metric, flat=True):
         self.__metric = lambda x, y: metric(x[1], y[1])
         self.__radius = radius
         self.__data = None
         self.__vptree = None
+        self.__flat = flat
+
+    def __flat_vpt(self):
+        return FVPT(self.__metric, self.__data, leaf_radius=self.__radius)
+
+    def __vpt(self):
+        return VPT(self.__metric, self.__data, leaf_radius=self.__radius)
 
     def fit(self, X):
         self.__data = list(enumerate(X))
-        self.__vptree = VPTree(
-            self.__metric, self.__data, leaf_radius=self.__radius)
+        self.__vptree = self.__flat_vpt() if self.__flat else self.__vpt()
         return self
 
     def search(self, x):
@@ -86,24 +96,34 @@ def search(self, x):
 class KNNCover(ProximityNetCover):
     '''
     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 `KNNCover.search` method returns the k nearest points to the target point.
+
+    This class implements the KNN Proximity function: after calling `fit`, the `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 flat: Set to True to use flat vptrees.
+    :type flat: `bool`
     '''
 
-    def __init__(self, neighbors, metric):
+    def __init__(self, neighbors, metric, flat=True):
         self.__neighbors = neighbors
         self.__metric = lambda x, y: metric(x[1], y[1])
         self.__data = None
         self.__vptree = None
+        self.__flat = flat
+
+    def __flat_vpt(self):
+        return FVPT(self.__metric, self.__data, leaf_capacity=self.__neighbors)
+
+    def __vpt(self):
+        return VPT(self.__metric, self.__data, leaf_capacity=self.__neighbors)
 
     def fit(self, X):
         self.__data = list(enumerate(X))
-        self.__vptree = VPTree(self.__metric, self.__data, leaf_capacity=self.__neighbors)
+        self.__vptree = self.__flat_vpt() if self.__flat else self.__vpt()
         return self
 
     def search(self, x):
@@ -116,26 +136,27 @@ def search(self, x):
 class CubicalCover(ProximityNetCover):
     '''
     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 `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.
+
+    This class implements the Cubical Proximity function: after calling `fit`, the `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 fraction.
-    :type overlap_frac: float in (0.0, 1.0).
+    :type overlap_frac: `float` in (0.0, 1.0).
+    :param flat: Set to True to use flat vptrees.
+    :type flat: `bool`
     '''
 
-    def __init__(self, n_intervals, overlap_frac):
+    def __init__(self, n_intervals, overlap_frac, flat=True):
         self.__n_intervals = n_intervals
-        self.__overlap_frac = overlap_frac
         self.__radius = 1.0 / (2.0 - 2.0 * overlap_frac)
         self.__minimum = None
         self.__maximum = None
         self.__delta = None
         metric = self._pullback(self._gamma_n, self._l_infty)
-        self.__ball_proximity = BallCover(self.__radius, metric)
+        self.__ball_proximity = BallCover(self.__radius, metric, flat=flat)
 
     def _l_infty(self, x, y):
         return np.max(np.abs(x - y)) # in alternative: np.linalg.norm(x - y, ord=np.inf)
@@ -163,16 +184,15 @@ def _set_bounds(self, data):
         for w in data:
             minimum = np.minimum(minimum, np.array(w))
             maximum = np.maximum(maximum, np.array(w))
-        self.__minimum = np.nan_to_num(minimum, nan=-eps)
-        self.__maximum = np.nan_to_num(maximum, nan=eps)
+        self.__minimum = np.nan_to_num(minimum, nan=-float(eps))
+        self.__maximum = np.nan_to_num(maximum, nan=float(eps))
         delta = self.__maximum - self.__minimum
-        eps = np.finfo(np.float64).eps
         self.__delta = np.maximum(eps, delta)
 
     def fit(self, X):
         self._set_bounds(X)
         self.__ball_proximity.fit(X)
-        return
+        return self
 
     def search(self, x):
         return self.__ball_proximity.search(self._phi(x))

src/tdamapper/plot.py

@@ -1,3 +1,4 @@
+'''A module for plotting the Mapper graph.'''
 import math
 
 import numpy as np
@@ -28,15 +29,15 @@ class MapperPlot:
     :param X: A dataset.
     :type X: `numpy.ndarray` or list-like.
     :param graph: The Mapper graph.
-    :type graph: `networkx.Graph`.
+    :type graph: `networkx.Graph`
     :param colors: A dataset of values to plot as nodes color.
     :type colors: `numpy.ndarray` or list-like.
     :param agg: Aggregation function that computes nodes color.
     :type agg: Callable on the values of colors.
     :param cmap: A colormap, to convert values into colors.
-    :type cmap: `str`.
-    :param **kwargs: Additional arguments to networkx.spring_layout.
-    :type: `dict`.
+    :type cmap: `str`
+    :param kwargs: Additional arguments to networkx.spring_layout.
+    :type: `dict`
     '''
 
     def __init__(
@@ -77,12 +78,12 @@ def plot(self, *args, style='interactive', **kwargs):
         '''
         Turns the plot object into a displayable figure.
 
-        :param *args: Arguments to supply.
-        :type *args: `list`.
+        :param args: Arguments to supply.
+        :type args: `list`
         :param style: The type of plot, can either be 'interactive' or 'static'.
-        :type style: `str`.
-        :param **kwargs: Additional arguments to supply.
-        :type: `dict`.
+        :type style: `str`
+        :param kwargs: Additional arguments to supply.
+        :type kwargs: `dict`
         '''
         if not self.__pos:
             return