New sphere graph

.gitignore

@@ -25,7 +25,9 @@ output/*.html
 output/*/index.html
 
 # Sphinx documentation
-doc/_build
+/doc/_build/
+/doc/examples/
+/doc/backrefs/
 
 # Vim swap files
 .*.swp

.readthedocs.yml

@@ -5,5 +5,4 @@ python:
   version: 3
   pip_install: true
   extra_requirements:
-    - alldeps
-    - doc
+    - dev

.travis.yml

@@ -19,7 +19,8 @@ matrix:
 addons:
   apt:
     packages:
-    - libqt5gui5  # pyqt5>5.11 fails to load the xcb platform plugin without it
+      - libqt5gui5  # pyqt5>5.11 otherwise cannot load the xcb platform plugin
+      - libflann-dev
 
 install:
   - pip install -U --upgrade-strategy eager .[alldeps,test,doc]

CONTRIBUTING.rst

@@ -14,7 +14,20 @@ The package can be set up (ideally in a virtual environment) for local
 development with the following::
 
     $ git clone https://github.com/epfl-lts2/pygsp.git
-    $ pip install -U -e pygsp[alldeps,test,doc,pkg]
+    $ pip install -U -e pygsp[dev]
+<<<<<<< HEAD
+
+The ``dev`` "extras requirement" ensures that dependencies required for
+development (to run the test suite and build the documentation) are installed.
+Only `graph-tool <https://graph-tool.skewed.de>`_ will be missing: install it
+manually as it cannot be installed by pip.
+=======
+>>>>>>> merge all the extra requirements in a single dev requirement
+
+The ``dev`` "extras requirement" ensures that dependencies required for
+development (to run the test suite and build the documentation) are installed.
+Only `graph-tool <https://graph-tool.skewed.de>`_ will be missing: install it
+manually as it cannot be installed by pip.
 
 You can improve or add functionality in the ``pygsp`` folder, along with
 corresponding unit tests in ``pygsp/tests/test_*.py`` (with reasonable
@@ -36,6 +49,13 @@ documentation with the following (enforced by Travis CI)::
 Check the generated coverage report at ``htmlcov/index.html`` to make sure the
 tests reasonably cover the changes you've introduced.
 
+To iterate faster, you can partially run the test suite, at various degrees of
+granularity, as follows::
+
+   $ python -m unittest pygsp.tests.test_docstrings.suite_reference
+   $ python -m unittest pygsp.tests.test_graphs.TestImportExport
+   $ python -m unittest pygsp.tests.test_graphs.TestImportExport.test_save_load
+
 Making a release
 ----------------
 

README.rst

@@ -2,6 +2,14 @@
 PyGSP: Graph Signal Processing in Python
 ========================================
 
+The PyGSP is a Python package to ease
+`Signal Processing on Graphs <https://arxiv.org/abs/1211.0053>`_.
+The documentation is available on
+`Read the Docs <https://pygsp.readthedocs.io>`_
+and development takes place on
+`GitHub <https://github.com/epfl-lts2/pygsp>`_.
+A (mostly unmaintained) `Matlab version <https://lts2.epfl.ch/gsp>`_ exists.
+
 +-----------------------------------+
 | |doc|  |pypi|  |conda|  |binder|  |
 +-----------------------------------+
@@ -26,18 +34,11 @@ PyGSP: Graph Signal Processing in Python
    :target: https://coveralls.io/github/epfl-lts2/pygsp
 .. |github| image:: https://img.shields.io/github/stars/epfl-lts2/pygsp.svg?style=social
    :target: https://github.com/epfl-lts2/pygsp
-.. |binder| image:: https://mybinder.org/badge.svg
+.. |binder| image:: https://mybinder.org/badge_logo.svg
    :target: https://mybinder.org/v2/gh/epfl-lts2/pygsp/master?filepath=playground.ipynb
 .. |conda| image:: https://anaconda.org/conda-forge/pygsp/badges/installer/conda.svg
    :target: https://anaconda.org/conda-forge/pygsp
 
-The PyGSP is a Python package to ease
-`Signal Processing on Graphs <https://arxiv.org/abs/1211.0053>`_.
-The documentation is available on
-`Read the Docs <https://pygsp.readthedocs.io>`_
-and development takes place on
-`GitHub <https://github.com/epfl-lts2/pygsp>`_.
-A (mostly unmaintained) `Matlab version <https://lts2.epfl.ch/gsp>`_ exists.
 
 The PyGSP facilitates a wide variety of operations on graphs, like computing
 their Fourier basis, filtering or interpolating signals, plotting graphs,
@@ -53,6 +54,15 @@ exponential window; and Gabor filters. Despite all the pre-defined models, you
 can easily use a custom graph by defining its adjacency matrix, and a custom
 filter bank by defining a set of functions in the spectral domain.
 
+While NetworkX_ and graph-tool_ are tools to analyze the topology of graphs,
+the aim of the PyGSP is to analyze graph signals, also known as features or
+properties (i.e., not the graph itself).
+Those three tools are complementary and work well together with the provided
+import / export facility.
+
+.. _NetworkX: https://networkx.github.io
+.. _graph-tool: https://graph-tool.skewed.de
+
 The following demonstrates how to instantiate a graph and a filter, the two
 main objects of the package.
 
@@ -100,13 +110,16 @@ The PyGSP is available on PyPI::
 
     $ pip install pygsp
 
-Note that you will need a recent version of ``pip`` and ``setuptools``. Please
-run ``pip install --upgrade pip setuptools`` if you get any installation error.
-
 The PyGSP is available on `conda-forge <https://github.com/conda-forge/pygsp-feedstock>`_::
 
     $ conda install -c conda-forge pygsp
 
+The PyGSP is available in the `Arch User Repository <https://aur.archlinux.org/packages/python-pygsp>`_::
+
+   $ git clone https://aur.archlinux.org/python-pygsp.git
+   $ cd python-pygsp
+   $ makepkg -csi
+
 Contributing
 ------------
 

doc/conf.py

@@ -2,11 +2,13 @@
 
 import pygsp
 
-extensions = ['sphinx.ext.viewcode',
-              'sphinx.ext.autosummary',
-              'sphinx.ext.mathjax',
-              'sphinx.ext.inheritance_diagram',
-              'sphinxcontrib.bibtex']
+extensions = [
+    'sphinx.ext.viewcode',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.inheritance_diagram',
+    'sphinxcontrib.bibtex',
+]
 
 extensions.append('sphinx.ext.autodoc')
 autodoc_default_flags = ['members', 'undoc-members']
@@ -37,6 +39,17 @@
 from pygsp import graphs, filters, utils, plotting
 """
 
+extensions.append('sphinx_gallery.gen_gallery')
+sphinx_gallery_conf = {
+    'examples_dirs': '../examples',
+    'gallery_dirs': 'examples',
+    'filename_pattern': '/',
+    'reference_url': {'pygsp': None},
+    'backreferences_dir': 'backrefs',
+    'doc_module': 'pygsp',
+    'show_memory': True,
+}
+
 exclude_patterns = ['_build']
 source_suffix = '.rst'
 master_doc = 'index'

doc/history.rst

@@ -24,6 +24,27 @@ History
 * New implementation of the Sensor graph that is simpler and scales better.
 * A new learning module with three functions to solve standard semi-supervised
   classification and regression problems.
+<<<<<<< HEAD
+<<<<<<< HEAD
+* A much improved, fixed, documented, and tested NNGraph. The user can now
+  select the backend and similarity kernel. The radius can be estimated and
+  features standardized. (PR #43)
+=======
+=======
+* Import and export graphs and their signals to NetworkX and graph-tool.
+* Save and load graphs and theirs signals to / from GraphML, GML, and GEXF.
+<<<<<<< HEAD
+>>>>>>> update I/O doc
+=======
+* Documentation: path graph linked to DCT, ring graph linked to DFT.
+<<<<<<< HEAD
+>>>>>>> doc: path and DCT, ring and DFT
+=======
+* We now have a gallery of examples! That is convenient for users to get a
+  taste of what the library can do, and to start working from a code snippet.
+>>>>>>> history: examples gallery
+* Merged all the extra requirements in a single dev requirement.
+>>>>>>> merge all the extra requirements in a single dev requirement
 
 Experimental filter API (to be tested and validated):
 
@@ -89,7 +110,7 @@ The following packages were made optional dependencies:
   workflow, it's not necessary for users who only want to process data without
   plotting graphs, signals and filters.
 * pyflann, as it is only used for approximate kNN. The problem was that the
-  source distribution would not build for Windows.  On conda-forge, (py)flann
+  source distribution would not build for Windows. On conda-forge, (py)flann
   is not built for Windows either.
 
 Moreover, matplotlib is now the default drawing backend. It's well integrated

doc/index.rst

@@ -5,6 +5,7 @@
 
    Home <self>
    tutorials/index
+   examples/index
    reference/index
    contributing
    history

doc/reference/index.rst

@@ -1,6 +1,6 @@
-===============
-Reference guide
-===============
+=============
+API reference
+=============
 
 .. automodule:: pygsp
 

doc/references.bib

@@ -77,15 +77,16 @@ @article{klein1993resistance
   publisher={Springer}
 }
 
-@article{strang1999discrete,
+@article{strang1999dct,
   title={The discrete cosine transform},
   author={Strang, Gilbert},
   journal={SIAM review},
   volume={41},
   number={1},
   pages={135--147},
   year={1999},
-  publisher={SIAM}
+  publisher={SIAM},
+  url={https://sci-hub.tw/10.1137/S0036144598336745},
 }
 
 @article{shuman2013spectrum,

doc/tutorials/optimization.rst

@@ -85,7 +85,7 @@ We start with the graph TV regularization. We will use the :class:`pyunlocbox.so
     >>> prob1 = pyunlocbox.solvers.solve([d, r, f], solver=solver,
     ...                                  x0=x0, rtol=0, maxit=1000)
     Solution found after 1000 iterations:
-        objective function f(sol) = 2.250584e+02
+        objective function f(sol) = 2.256055e+02
         stopping criterion: MAXIT
     >>>
     >>> fig, ax = G.plot(prob1['sol'])
@@ -107,7 +107,7 @@ This figure shows the label signal recovered by graph total variation regulariza
     >>> prob2 = pyunlocbox.solvers.solve([r, f], solver=solver,
     ...                                  x0=x0, rtol=0, maxit=1000)
     Solution found after 1000 iterations:
-        objective function f(sol) = 6.504290e+01
+        objective function f(sol) = 4.376481e+01
         stopping criterion: MAXIT
     >>>
     >>> fig, ax = G.plot(prob2['sol'])

examples/README.txt

@@ -0,0 +1,3 @@
+========
+Examples
+========

examples/eigenvalue_concentration.py

@@ -0,0 +1,38 @@
+r"""
+Concentration of the eigenvalues
+================================
+
+The eigenvalues of the graph Laplacian concentrates to the same value as the
+graph becomes full.
+"""
+
+import numpy as np
+from matplotlib import pyplot as plt
+import pygsp as pg
+
+n_neighbors = [1, 2, 5, 8]
+fig, axes = plt.subplots(3, len(n_neighbors), figsize=(15, 8))
+
+for k, ax in zip(n_neighbors, axes.T):
+
+    graph = pg.graphs.Ring(17, k=k)
+    graph.compute_fourier_basis()
+    graph.plot(graph.U[:, 1], ax=ax[0])
+    ax[0].axis('equal')
+    ax[1].spy(graph.W)
+    ax[2].plot(graph.e, '.')
+    ax[2].set_title('k={}'.format(k))
+    #graph.set_coordinates('line1D')
+    #graph.plot(graph.U[:, :4], ax=ax[3], title='')
+
+    # Check that the DFT matrix is an eigenbasis of the Laplacian.
+    U = np.fft.fft(np.identity(graph.n_vertices))
+    LambdaM = (graph.L.todense().dot(U)) / (U + 1e-15)
+    # Eigenvalues should be real.
+    assert np.all(np.abs(np.imag(LambdaM)) < 1e-10)
+    LambdaM = np.real(LambdaM)
+    # Check that the eigenvectors are really eigenvectors of the laplacian.
+    Lambda = np.mean(LambdaM, axis=0)
+    assert np.all(np.abs(LambdaM - Lambda) < 1e-10)
+
+fig.tight_layout()

examples/filtering.py

@@ -0,0 +1,66 @@
+r"""
+Filtering a graph signal
+========================
+
+A graph signal is filtered by transforming it to the spectral domain (via the
+Fourier transform), performing a point-wise multiplication (motivated by the
+convolution theorem), and transforming it back to the vertex domain (via the
+inverse graph Fourier transform).
+
+.. note::
+
+    In practice, filtering is implemented in the vertex domain to avoid the
+    computationally expensive graph Fourier transform. To do so, filters are
+    implemented as polynomials of the eigenvalues / Laplacian. Hence, filtering
+    a signal reduces to its multiplications with sparse matrices (the graph
+    Laplacian).
+
+"""
+
+import numpy as np
+from matplotlib import pyplot as plt
+import pygsp as pg
+
+G = pg.graphs.Sensor(seed=42)
+G.compute_fourier_basis()
+
+#g = pg.filters.Rectangular(G, band_max=0.2)
+g = pg.filters.Expwin(G, band_max=0.5)
+
+fig, axes = plt.subplots(1, 3, figsize=(12, 4))
+fig.subplots_adjust(hspace=0.5)
+
+x = np.random.RandomState(1).normal(size=G.N)
+#x = np.random.RandomState(42).uniform(-1, 1, size=G.N)
+x = 3 * x / np.linalg.norm(x)
+y = g.filter(x)
+x_hat = G.gft(x).squeeze()
+y_hat = G.gft(y).squeeze()
+
+limits = [x.min(), x.max()]
+
+G.plot(x, limits=limits, ax=axes[0], title='input signal $x$ in the vertex domain')
+axes[0].text(0, -0.1, '$x^T L x = {:.2f}$'.format(G.dirichlet_energy(x)))
+axes[0].set_axis_off()
+
+g.plot(ax=axes[1], alpha=1)
+line_filt = axes[1].lines[-2]
+line_in, = axes[1].plot(G.e, np.abs(x_hat), '.-')
+line_out, = axes[1].plot(G.e, np.abs(y_hat), '.-')
+#axes[1].set_xticks(range(0, 16, 4))
+axes[1].set_xlabel(r'graph frequency $\lambda$')
+axes[1].set_ylabel(r'frequency content $\hat{x}(\lambda)$')
+axes[1].set_title(r'signals in the spectral domain')
+axes[1].legend(['input signal $\hat{x}$'])
+labels = [
+    r'input signal $\hat{x}$',
+    'kernel $g$',
+    r'filtered signal $\hat{y}$',
+]
+axes[1].legend([line_in, line_filt, line_out], labels, loc='upper right')
+
+G.plot(y, limits=limits, ax=axes[2], title='filtered signal $y$ in the vertex domain')
+axes[2].text(0, -0.1, '$y^T L y = {:.2f}$'.format(G.dirichlet_energy(y)))
+axes[2].set_axis_off()
+
+fig.tight_layout()