Merge pull request #164 from sknetwork-team/develop

Develop
sknetwork-team · Jul 17, 2019 · e56d85c · e56d85c
2 parents 13ee648 + f00e2d1
commit e56d85c
Show file tree

Hide file tree

Showing 70 changed files with 10,388 additions and 7,756 deletions.
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -2,6 +2,14 @@
 History
 =======
 
+0.8.0 (2019-07-17)
+------------------
+
+* Changed Louvain, BiLouvain, Paris and PageRank APIs
+* Changed PageRank method
+* Documentation overhaul
+* Improved Jupyter tutorials
+
 0.7.1 (2019-07-04)
 ------------------
 

diff --git a/README.rst b/README.rst
@@ -43,3 +43,6 @@ To use scikit-network in a project::
 
     import sknetwork as skn
 
+See examples in the Tutorials_ section.
+
+.. _Tutorials: https://scikit-network.readthedocs.io/en/latest/tutorials/
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -0,0 +1,37 @@
+html  {
+    background-color: #e6e6e6;
+}
+
+body.wy-body-for-nav {
+    line-height: 1.5em;
+    color: #333;
+}
+
+div.wy-nav-side {
+    background-color: #333;
+}
+
+div.wy-side-nav-search {
+    background-color: #777777;
+}
+
+
+div.wy-menu.wy-menu-vertical>p {
+    color: #ffffff /* section titles */
+}
+
+.wy-nav-top {
+    background-color: #777777;
+}
+
+.wy-side-nav-search>a:hover, .wy-side-nav-search .wy-dropdown>a:hover {
+    background: None; /*background for logo when hovered*/
+}
+
+.wy-side-nav-search>div.version {
+    color: white;
+}
+
+.wy-side-nav-search input[type=text] {
+    border-color: #d9d9d9;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -20,10 +20,9 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('..'))
-
 import sknetwork
 
+sys.path.insert(0, os.path.abspath('..'))
 # -- General configuration ---------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -47,7 +46,7 @@
 
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = []
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -90,14 +89,17 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-
 # -- Options for HTML output -------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
-
+html_logo = '../images/logo_sknetwork_long.png'
+html_theme_options = {
+    'logo_only': True
+}
+html_scaled_image_link = False
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the
 # documentation.
@@ -107,7 +109,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ['_static']
 
 
 # -- Options for HTMLHelp output ---------------------------------------
@@ -172,4 +174,5 @@
 ]
 
 
-
+def setup(app):
+    app.add_stylesheet('css/custom.css')
diff --git a/docs/genindex.rst b/docs/genindex.rst
@@ -0,0 +1,2 @@
+Index
+=====
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,25 +1,31 @@
-.. figure:: ../images/logo_sknetwork.png
-    :align: right
-    :width: 200px
-    :alt: logo sknetwork
-
 Welcome to scikit-network's documentation!
 ==========================================
 
+.. include:: readme.rst
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Installation & Reference
 
-   readme
    installation
    reference/index
-   tutorials/index
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
+
+   tutorials/clustering_Louvain
+   tutorials/hierarchical_clustering
+   tutorials/pagerank
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: About
+
    contributing
    authors
    history
+   genindex
 
-Indices and tables
-==================
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/reference/clustering.rst b/docs/reference/clustering.rst
@@ -5,8 +5,7 @@ Clustering
 
 .. currentmodule:: sknetwork
 
-This submodule contains clustering algorithms, characterized by their ``.labels_`` attribute which assigns a cluster to
-each node in the graph.
+This module contains clustering algorithms. The attribute ``.labels_``  assigns a cluster to each node of the graph.
 
 Louvain
 -------
@@ -33,7 +32,3 @@ Metrics
 .. autofunction:: sknetwork.clustering.bimodularity
 
 .. autofunction:: sknetwork.clustering.cocitation_modularity
-
-.. autofunction:: sknetwork.clustering.performance
-
-.. autofunction:: sknetwork.clustering.cocitation_performance
diff --git a/docs/reference/embedding.rst b/docs/reference/embedding.rst
@@ -5,8 +5,7 @@ Embedding
 
 .. currentmodule:: sknetwork
 
-This submodule contains embedding algorithms, characterized by their ``.embedding_`` attribute which assigns a dense
-vector representation to each node in the graph.
+This module contains embedding algorithms. The attribute ``.embedding_`` assigns a vector to each node of the graph.
 
 
 Spectral

diff --git a/docs/reference/hierarchy.rst b/docs/reference/hierarchy.rst
@@ -5,28 +5,24 @@ Hierarchical clustering
 
 .. currentmodule:: sknetwork
 
-This submodule contains embedding algorithms, characterized by their ``.dendrogram_`` attribute.
+This module contains hierarchical clustering algorithms. The attribute ``.dendrogram_`` contains the dendrogram.
 
-A dendrogram is an :math:`(n-1) \times 4` array ``Z`` representing the successive merges of clusters i.e.
-clsuters with indices ``Z[i, 0]`` and ``Z[i, 1]`` which are at distance ``Z[i, 2]`` are merged into cluster :math:`n+i`
-which contains ``Z[i, 3]`` samples.
+A dendrogram is an :math:`(n-1) \times 4` array ``Z`` representing the successive merges of clusters, i.e.,
+clusters of indices ``Z[i, 0]`` and ``Z[i, 1]``, which are at distance ``Z[i, 2]``, are merged into cluster of index
+:math:`n+i`, which contains ``Z[i, 3]`` nodes.
 
 
 Paris
 -----
 .. automodule:: sknetwork.hierarchy
-.. autosummary::
-   :toctree: generated/
 
 .. autoclass:: sknetwork.hierarchy.Paris
     :members:
 
 
-Utils
------
-.. autofunction:: sknetwork.hierarchy.reorder_dendrogram
-
-.. autofunction:: sknetwork.hierarchy.cut
+Cuts of the dendrogram
+----------------------
+.. autofunction:: sknetwork.hierarchy.straight_cut
 
 
 

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -10,6 +10,7 @@ Reference
     clustering
     hierarchy
     ranking
+    linalg
     loader
     toy_graphs
     utils
diff --git a/docs/reference/introduction.rst b/docs/reference/introduction.rst
@@ -23,19 +23,58 @@ To use scikit-network in a project::
     import sknetwork as skn
 
 
-About the documentation
------------------------
-
-We use the following notations in the documentation:
+Optional dependency
+-------------------
 
-* :math:`A` denotes the adjacency matrix for undirected and directed graphs.
+Numba_ is not listed as an explicit dependency for scikit-network. However it is automatically
+used whenever possible -  unless specified otherwise by the user - in order to speed algorithm executions up.
 
-* :math:`B` denotes the biadjacency matrix for bipartite graphs (possibly non-square).
+Note that when using a Numba-accelerated function for the first time in a session,
+just-in-time compilation takes a few seconds.
 
-* :math:`d = A1` or :math:`B1` is the out-degree vector and :math:`D = \text{diag}(d)` the associated diagonal matrix.
-
-* :math:`f = A^T1` or :math:`B^T1` is the in-degree vector and :math:`F = \text{diag}(f)` the associated diagonal matrix.
+About the documentation
+-----------------------
 
-* :math:`w = 1^T A1` or :math:`1 ^T B1` is the total weight of the graph.
+We use the following notations in the documentation:
 
+Undirected graphs
+^^^^^^^^^^^^^^^^^
+
+* :math:`A` is the adjacency matrix of the graph (dimension :math:`n\times n`)
+* :math:`d = A1` is the vector of node weights (node degrees if the matrix :math:`A` is binary)
+* :math:`D = \text{diag}(d)` the diagonal matrix of node weights
+* :math:`L = D - A` is the Laplacian matrix of the graph
+* :math:`P = D^{-1}A` is the transition matrix of the random walk in the graph (for positive node weights)
+* :math:`w = 1^T A1` is the total weight of the graph (total weight of nodes)
+
+Directed graphs
+^^^^^^^^^^^^^^^
+
+* :math:`A` is the adjacency matrix of the graph (dimension :math:`n\times n`)
+* :math:`d^+ = A1` is the vector of node out-weights (node out-degrees if the matrix :math:`A` is binary)
+* :math:`D^+ = \text{diag}(d^+)` is the diagonal matrix of node out-weights
+* :math:`P^+= {D^+}^{-1}A` is the transition matrix of the random walk in the graph (for positive node out-weights)
+* :math:`d^- = A1` is the vector of node in-weights (node in-degrees if the matrix :math:`A` is binary)
+* :math:`D^- = \text{diag}(d^-)` is the diagonal matrix of node in-weights
+* :math:`P^-= {D^-}^{-1}A` is the transition matrix of the random walk in reverse direction (for positive node in-weights)
+* :math:`w = 1^T A1` is the total weight of the graph (total weight of nodes)
+
+Bipartite graphs
+^^^^^^^^^^^^^^^^
+
+* :math:`B` denotes the biadjacency matrix of the graph (dimension :math:`n\times p`); rows and columns are viewed as samples and features
+* :math:`d = B1` is the vector of sample weights
+* :math:`D = \text{diag}(d)` is the diagonal matrix of sample weights
+* :math:`f = B^T1` is the vector of feature weights
+* :math:`F = \text{diag}(f)` the diagonal matrix of feature weights
+* :math:`w = 1^T B1` is the total weight of the graph (total weight of edges)
+
+Notes
+^^^^^
+
+* Adjacency and biadjacency matrices have non-negative entries (the edges of the graph)
+* Nodes are indexed from 1 to :math:`n` in the documentation and from 0 to :math:`n-1` in the code
+* Bipartite graphs are undirected but have a special structure that is exploited by some algorithms
+
+.. _Numba: https://numba.pydata.org
 
diff --git a/docs/reference/linalg.rst b/docs/reference/linalg.rst
@@ -0,0 +1,38 @@
+.. _linalg:
+
+Linear algebra
+**************
+
+.. currentmodule:: sknetwork
+
+Submodule for linear Algebra.
+
+Sparse + Low Rank structure
+---------------------------
+
+.. autoclass:: sknetwork.linalg.SparseLR
+    :members:
+
+Solvers
+-------
+
+.. autoclass:: sknetwork.linalg.LanczosEig
+    :members:
+
+.. autoclass:: sknetwork.linalg.HalkoEig
+    :members:
+
+.. autoclass:: sknetwork.linalg.LanczosSVD
+    :members:
+
+.. autoclass:: sknetwork.linalg.HalkoSVD
+    :members:
+
+Randomized methods
+------------------
+
+.. autofunction:: sknetwork.linalg.randomized_matrix_factorization.randomized_range_finder
+
+.. autofunction:: sknetwork.linalg.randomized_svd
+
+.. autofunction:: sknetwork.linalg.randomized_eig
diff --git a/docs/reference/ranking.rst b/docs/reference/ranking.rst
@@ -5,10 +5,12 @@ Ranking
 
 .. currentmodule:: sknetwork
 
-This submodule contains ranking algorithms, characterized by their ``.ranking_`` attribute which assigns an importance
-score to each node in the graph.
+This module contains ranking algorithms. The attribute ``.ranking_`` assigns an importance
+score to each node of the graph.
 
-Pagerank
+PageRank
 --------
+.. automodule:: sknetwork.ranking
+
 .. autoclass:: sknetwork.ranking.PageRank
     :members:
diff --git a/docs/reference/toy_graphs.rst b/docs/reference/toy_graphs.rst
@@ -5,10 +5,29 @@ Toy graphs
 
 .. currentmodule:: sknetwork
 
-.. autofunction:: sknetwork.toy_graphs.bow_tie_graph
+Undirected graphs
+=================
 
-.. autofunction:: sknetwork.toy_graphs.house_graph
+.. autofunction:: sknetwork.toy_graphs.bow_tie
+
+.. autofunction:: sknetwork.toy_graphs.house
+
+.. autofunction:: sknetwork.toy_graphs.karate_club
+
+.. autofunction:: sknetwork.toy_graphs.miserables
+
+Directed graphs
+===============
+
+.. autofunction:: sknetwork.toy_graphs.painters
+
+.. autofunction:: sknetwork.toy_graphs.rock_paper_scissors
+
+Bipartite graphs
+================
+
+.. autofunction:: sknetwork.toy_graphs.movie_actor
+
+.. autofunction:: sknetwork.toy_graphs.star_wars_villains
 
-.. autofunction:: sknetwork.toy_graphs.karate_club_graph
 
-.. autofunction:: sknetwork.toy_graphs.star_wars_villains_graph
Original file line number	Diff line number	Diff line change
Expand Up		@@ -43,3 +43,6 @@ To use scikit-network in a project::

		import sknetwork as skn

		See examples in the Tutorials_ section.

		.. _Tutorials: https://scikit-network.readthedocs.io/en/latest/tutorials/