update formatting of many docstrings

scikit-tda · Nov 8, 2018 · 14845cb · 14845cb
1 parent 8f7dcb6
commit 14845cb
Show file tree

Hide file tree

Showing 12 changed files with 153 additions and 64 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -6,10 +6,10 @@ python:
   - "3.6"
 
 matrix:
-include:
-  - python: 3.7
-    dist: xenial
-    sudo: true
+  include:
+    - python: 3.7
+      dist: xenial
+      sudo: true
 
 before_install:
     # Tricks to avoid matplotlib error about X11:

diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -78,6 +78,21 @@
   {# Keep modernizr in head - http://modernizr.com/docs/#installing #}
   <script src="{{ pathto('_static/js/modernizr.min.js', 1) }}"></script>
 
+  <!-- Google Analytics -->
+  <script>
+    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+    m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+    })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+
+    ga('create', '{{ google_code }}', 'auto');
+    ga('send', 'pageview');
+  </script>
+    <!-- End Google Analytics -->
+
+
+
+
 </head>
 
 <body class="wy-body-for-nav">

diff --git a/docs/conf.py b/docs/conf.py
@@ -20,7 +20,7 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
-
+autodoc_member_order = 'bysource'
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -31,10 +31,16 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 
+from kmapper import __version__
+
+
 import sys
 sys.path.append("../.")
 
-googleanalytics_id = 'UA-124965309-4'
+
+
+
+html_context = {'google_code': 'UA-124965309-4'}
 
 extensions = [
     'sphinx.ext.autodoc',
@@ -46,7 +52,6 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.githubpages',
     'nbsphinx',
-    'sphinxcontrib.googleanalytics',
 ]
 
 numpydoc_show_class_members = False
@@ -71,10 +76,10 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = u'1.0'
-# The full version, including alpha/beta/rc tags.
-release = u'1.0.1'
+# The short X.Y version
+version = __version__
+# The full version, including alpha/beta/rc tags
+release = __version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/index.rst b/docs/index.rst
@@ -20,7 +20,7 @@ Contents
 --------
 
 .. toctree::
-  :maxdepth: 2
+  :maxdepth: 1
 
   about
   setup
@@ -29,7 +29,7 @@ Contents
   reference
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
     :caption: Tutorials
 
     KeplerMapper Newsgroup20 Pipeline

diff --git a/docs/reference.rst b/docs/reference.rst
@@ -1,19 +1,12 @@
 
-Reference
-----------
+API Reference
+---------------
 
 .. automodule:: kmapper
 
 
-KeplerMapper
-==============
-.. code:: python
-
-    mapper = km.KeplerMapper(verbose=1)
-
-.. automodule:: kmapper.kmapper
-   :members:
-
+.. autoclass:: KeplerMapper
+    :members: project, fit_transform, map, visualize, data_from_cluster_id
 
 Cover Schemes
 =========================
@@ -29,3 +22,19 @@ Nerves
 
 .. automodule:: kmapper.nerve
    :members:
+
+
+Adapters
+=============
+
+.. automodule:: kmapper.adapter
+    :members:
+
+Visuals
+==========
+
+.. automodule:: kmapper.jupyter
+    :members:
+
+.. automodule:: kmapper.plotlyviz
+    :members: plotlyviz, mpl_to_plotly
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+nbsphinx
+numpydoc
+sphinx_rtd_theme
diff --git a/kmapper/adapter.py b/kmapper/adapter.py
@@ -7,6 +7,17 @@
 
 def to_networkx(graph):
     """ Convert a Mapper 1-complex to a networkx graph.
+
+    Parameters
+    -----------
+
+    graph: dictionary, graph object returned from `kmapper.map`
+
+    Returns
+    --------
+
+    g: graph as networkx.Graph() object
+
     """
 
     # import here so networkx is not always required.

diff --git a/kmapper/cover.py b/kmapper/cover.py
@@ -9,6 +9,17 @@
 
 class Cover:
     """Helper class that defines the default covering scheme
+
+
+    Parameters
+    ------------
+
+    limits: Numpy Array (n_dim,2)
+        (lower bound, upper bound) for every dimension
+        If a value is set to `np.float('inf')`, the bound will be assumed to be the min/max value of the dimension
+        Also, if `limits == None`, the limits are defined by the maximum and minimum value of the lens for all dimensions.
+        i.e. `[[min_1, max_1], [min_2, max_2], [min_3, max_3]]`
+
     """
 
     def __init__(
@@ -20,24 +31,13 @@ def __init__(
         overlap_perc=None,
         limits=None,
     ):
-        """
-        limits: Numpy Array (n_dim,2)
-            (lower bound, upper bound) for every dimension
-            If a value is set to np.float('inf'), the bound will be assumed to be the min/max value of the dimension
-            Also, if limits == None, the limits are defined by the maximum and minimum value of the lens
-            for all dimensions.
-            i.e.
-                [[min_1, max_1],
-                 [min_2, max_2],
-                 [min_3, max_3]]
-        """
 
         self.n_cubes = nr_cubes if nr_cubes else n_cubes
         self.perc_overlap = overlap_perc if overlap_perc else perc_overlap
 
         if overlap_perc is not None or nr_cubes is not None:
             warnings.warn(
-                "Arguements `overlap_perc` and `nr_cubes` have been replaced with `perc_overlap` and `n_cubes`. Use `perc_overlap` and `n_cubes` instead. They will be removed in future releases.",
+                "Arguments `overlap_perc` and `nr_cubes` have been replaced with `perc_overlap` and `n_cubes`. Use `perc_overlap` and `n_cubes` instead. They will be removed in future releases.",
                 DeprecationWarning,
             )
 
@@ -58,7 +58,7 @@ def define_bins(self, data):
         Warning: This function must assume that the first column of data are indices.
         
         Examples
-        =========
+        ---------
 
             If there are 4 cubes per dimension and 3 dimensions return the bottom left (origin) coordinates of 64 hypercubes, as a sorted list of Numpy arrays
         """
@@ -159,7 +159,7 @@ def find_entries(self, data, cube, verbose=0):
 
 class CubicalCover(Cover):
     """
-    Explicit definition of a cubical cover as the default behavior of the cover class
+    Explicit definition of a cubical cover as the default behavior of the cover class. This is currently identical to the default cover class.
     """
 
     pass
diff --git a/kmapper/kmapper.py b/kmapper/kmapper.py
@@ -78,22 +78,19 @@ class KeplerMapper(object):
     KM has a number of nice features, some which get forgotten.
         - project : Some projections it makes sense to use a distance matrix, such as knn_distance_#. Using `distance_matrix = <metric>` for a custom metric.
         - fit_transform : Applies a sequence of projections. Currently, this API is a little confusing and will be changed in the future. 
-        - 
+    
 
+    
+    Parameters
+    ===========
 
+    verbose: int, default is 0
+        Logging level. Currently 3 levels (0,1,2) are supported. For no logging, set `verbose=0`. For some logging, set `verbose=1`. For complete logging, set `verbose=2`.
+        
     """
 
     def __init__(self, verbose=0):
-        """
-        Inputs
-        ======
-
-        verbose: int, default is 0
-            Logging level. Currently 3 levels (0,1,2) are supported.
-                - for no logging, set `verbose=0`, 
-                - for some logging, set `verbose=1`,
-                - for complete logging, set `verbose=2`
-        """
+
 
         # TODO: move as many of the arguments from fit_transform and map into here.
         self.verbose = verbose
@@ -272,8 +269,6 @@ def fit_transform(
     ):
         """ Same as .project() but accepts lists for arguments so you can chain.
 
-            Deprecated.
-
         """
 
         projections = projection
@@ -508,7 +503,7 @@ def map(
                 if self.verbose > 1:
                     print("Cube_%s is empty.\n" % (i))
 
-        links, simplices = nerve(nodes)
+        links, simplices = nerve.compute(nodes)
 
         graph["nodes"] = nodes
         graph["links"] = links
@@ -590,12 +585,13 @@ def visualize(
             Number of bins shown in histogram of tooltip color distributions.
 
         Returns
-        ------
+        --------
         html: string
             Returns the same html that is normally output to `path_html`. Complete graph and data ready for viewing.
 
         Examples
-        -------
+        ---------
+
         >>> mapper.visualize(simplicial_complex, path_html="mapper_visualization_output.html",
                             custom_meta={'Data': 'MNIST handwritten digits', 
                                          'Created by': 'Franklin Roosevelt'

diff --git a/kmapper/nerve.py b/kmapper/nerve.py
@@ -5,24 +5,29 @@
 class Nerve:
     """Base class for implementations of a nerve finder to build a Mapper complex.
 
-    __call__: Return all simplices found by the nerve finder
     """
 
     def __init__(self):
         pass
 
-    def __call__(self, nodes, links):
+    def compute(self, nodes, links):
         raise NotImplementedError()
 
 
 class GraphNerve(Nerve):
     """ Creates the 1-skeleton of the Mapper complex.
+
+    Parameters
+    -----------
+
+    min_intersection: int, default is 1
+        Minimum intersection considered when computing the nerve. An edge will be created only when the intersection between two nodes is greater than or equal to `min_intersection`
     """
 
     def __init__(self, min_intersection=1):
         self.min_intersection = min_intersection
 
-    def __call__(self, nodes):
+    def compute(self, nodes):
         """Helper function to find edges of the overlapping clusters.
 
         Parameters
@@ -63,5 +68,5 @@ class SimplicialNerve(Nerve):
     Warning: Not implemented yet.
     """
 
-    def __call__(self, nodes, links=None):
+    def compute(self, nodes, links=None):
         pass
diff --git a/kmapper/plotlyviz.py b/kmapper/plotlyviz.py
@@ -80,6 +80,51 @@ def plotlyviz(
     member_textbox_width=800,
     filename=None
 ):
+    """
+        Visualizations and dashboards for kmapper graphs using Plotly. This method is suitable for use in Jupyter notebooks.
+
+        Parameters
+        -----------
+
+        scomplex: dict
+            Simplicial complex is the output from the KeplerMapper `map` method.
+    
+        title: str
+            Title of output graphic
+
+        graph_layout: igraph layout; 
+            recommended 'kk' (kamada-kawai) or 'fr' (fruchterman-reingold)
+        
+        colorscale: 
+             Plotly colorscale(colormap) to color graph nodes
+
+
+        dashboard: bool, default is False
+            If true, display complete dashboard of node information
+
+        graph_data: bool, default is False
+            If true, display graph metadata
+
+        factor_size: double, default is 3
+            a factor for the node size
+
+        edge_linewidth : double, default is 1.5
+        node_linecolor: color str, default is "rgb(200,200,200)"
+        width: int, default is 600,
+        height: int, default is 500,
+        bgcolor: color str, default is "rgba(240, 240, 240, 0.95)",
+        left: int, default is 10,
+        bottom: int, default is 35,
+        summary_height: int, default is 300,
+        summary_width: int, default is 600, 
+        summary_left: int, default is 20,
+        summary_right: int, default is 20,
+        hist_left: int, default is 25,
+        hist_right: int, default is 25,
+        member_textbox_width: int, default is 800, 
+        filename: str, default is None
+            if filename is given, the graphic will be saved to that file.
+    """
 
     kmgraph, mapper_summary, n_color_distribution = get_mapper_graph(
         scomplex, colorscale=colorscale, color_function=color_function,