Merge pull request #57 from lucasimi/feature/alignement

Improved docstrings

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()
@@ -91,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()
@@ -124,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()
@@ -142,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):
@@ -152,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

@@ -8,13 +8,13 @@
 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)
@@ -28,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):
@@ -56,15 +56,16 @@ 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.
+    :type flat: `bool`
     '''
 
     def __init__(self, radius, metric, flat=True):
@@ -95,15 +96,16 @@ 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.
+    :type flat: `bool`
     '''
 
     def __init__(self, neighbors, metric, flat=True):
@@ -134,17 +136,17 @@ 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.
+    :type flat: `bool`
     '''
 
     def __init__(self, n_intervals, overlap_frac, flat=True):

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