Merge branch 'master' into polynomial-approximations

Get the plotting updates.

Author: mdeff

.zenodo.json

@@ -0,0 +1,39 @@
+{
+	"title": "PyGSP: Graph Signal Processing in Python",
+	"description": "The PyGSP facilitates a wide variety of operations on graphs, like computing their Fourier basis, filtering or interpolating signals, plotting graphs, signals, and filters.",
+	"upload_type": "software",
+	"license": "BSD-3-Clause",
+	"access_right": "open",
+	"creators": [
+		{
+			"name": "Micha\u00ebl Defferrard",
+			"affiliation": "EPFL",
+			"orcid": "0000-0002-6028-9024"
+		},
+		{
+			"name": "Lionel Martin",
+			"affiliation": "EPFL"
+		},
+		{
+			"name": "Rodrigo Pena",
+			"affiliation": "EPFL"
+		},
+		{
+			"name": "Nathana\u00ebl Perraudin",
+			"affiliation": "EPFL",
+			"orcid": "0000-0001-8285-1308"
+		}
+	],
+	"related_identifiers": [
+		{
+			"scheme": "url",
+			"identifier": "https://github.com/epfl-lts2/pygsp",
+			"relation": "isSupplementTo"
+		},
+		{
+			"scheme": "doi",
+			"identifier": "10.5281/zenodo.1003157",
+			"relation": "isPartOf"
+		}
+	]
+}

CONTRIBUTING.rst

@@ -57,6 +57,9 @@ Making a release
 
    Log in as the LTS2 user.
 #. Build and upload the distribution to the real PyPI with ``make release``.
+#. Update the conda feedstock (at least the version number and sha256 in
+   ``recipe/meta.yaml``) by sending a PR to
+   `conda-forge <https://github.com/conda-forge/pygsp-feedstock>`_.
 
 Repository organization
 -----------------------

README.rst

@@ -14,7 +14,7 @@ PyGSP: Graph Signal Processing in Python
    :target: https://pygsp.readthedocs.io
 .. |pypi| image:: https://img.shields.io/pypi/v/pygsp.svg
    :target: https://pypi.python.org/pypi/PyGSP
-.. |zenodo| image:: https://zenodo.org/badge/16276560.svg
+.. |zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1003157.svg
    :target: https://doi.org/10.5281/zenodo.1003157
 .. |license| image:: https://img.shields.io/pypi/l/pygsp.svg
    :target: https://github.com/epfl-lts2/pygsp/blob/master/LICENSE.txt
@@ -33,13 +33,11 @@ PyGSP: Graph Signal Processing in Python
 
 The PyGSP is a Python package to ease
 `Signal Processing on Graphs <https://arxiv.org/abs/1211.0053>`_.
-It is a free software, distributed under the BSD license, and
-available on `PyPI <https://pypi.python.org/pypi/PyGSP>`_.
 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 `Matlab counterpart <https://lts2.epfl.ch/gsp>`_ exists.)
+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,
@@ -60,8 +58,15 @@ main objects of the package.
 
 >>> from pygsp import graphs, filters
 >>> G = graphs.Logo()
->>> G.estimate_lmax()
->>> g = filters.Heat(G, tau=100)
+>>> G.compute_fourier_basis()  # Fourier to plot the eigenvalues.
+>>> # G.estimate_lmax() is otherwise sufficient.
+>>> g = filters.Heat(G, tau=50)
+>>> g.plot()
+
+.. image:: ../pygsp/data/readme_example_filter.png
+    :alt:
+.. image:: pygsp/data/readme_example_filter.png
+    :alt:
 
 Let's now create a graph signal: a set of three Kronecker deltas for that
 example. We can now look at one step of heat diffusion by filtering the deltas
@@ -73,11 +78,11 @@ structure!
 >>> s = np.zeros(G.N)
 >>> s[DELTAS] = 1
 >>> s = g.filter(s)
->>> G.plot_signal(s, highlight=DELTAS, backend='matplotlib')
+>>> G.plot_signal(s, highlight=DELTAS)
 
-.. image:: ../pygsp/data/readme_example.png
+.. image:: ../pygsp/data/readme_example_graph.png
     :alt:
-.. image:: pygsp/data/readme_example.png
+.. image:: pygsp/data/readme_example_graph.png
     :alt:
 
 You can
@@ -86,7 +91,7 @@ look at the
 `tutorials <https://pygsp.readthedocs.io/en/stable/tutorials/index.html>`_
 to learn how to use it, or look at the
 `reference guide <https://pygsp.readthedocs.io/en/stable/reference/index.html>`_
-for an exhaustive documentation of the API. Enjoy the package!
+for an exhaustive documentation of the API. Enjoy!
 
 Installation
 ------------
@@ -115,6 +120,16 @@ research purpose at the `EPFL LTS2 laboratory <https://lts2.epfl.ch>`_.
 This project has been partly funded by the Swiss National Science Foundation
 under grant 200021_154350 "Towards Signal Processing on Graphs".
 
+The code in this repository is released under the terms of the `BSD 3-Clause license <LICENSE.txt>`_.
+
 If you are using the library for your research, for the sake of
 reproducibility, please cite the version you used as indexed by
 `Zenodo <https://doi.org/10.5281/zenodo.1003157>`_.
+Or cite the generic concept as::
+
+    @misc{pygsp,
+      title = {PyGSP: Graph Signal Processing in Python},
+      author = {Defferrard, Micha\"el and Martin, Lionel and Pena, Rodrigo and Perraudin, Nathana\"el},
+      doi = {10.5281/zenodo.1003157},
+      url = {https://github.com/epfl-lts2/pygsp/},
+    }

doc/history.rst

@@ -2,7 +2,7 @@
 History
 =======
 
-0.6.0 (2018-03-xx)
+0.6.0 (2018-04-xx)
 ------------------
 
 Filters approximated by Chebyshev polynomials are now implemented as separate
@@ -22,6 +22,17 @@ order 10. The reasons are multiple:
 
 See the new tutorial on filter approximations for usage.
 
+The plotting interface was updated to be more user-friendly. First, the
+documentation is now shown for filters.plot(), G.plot(), and co. Second, the
+API in the plotting library has been deprecated. That module is now mostly for
+implementation only. Finally, the following parameter names were changed:
+* plot_name => title
+* plot_eigenvalues => eigenvalues
+* show_sum => sum
+* show_edges => edges
+* npoints => n
+* save_as => save
+
 0.5.1 (2017-12-15)
 ------------------
 

doc/tutorials/intro.rst

@@ -193,7 +193,7 @@ let's define and plot that low-pass filter:
     >>> g = filters.Filter(G, g)
     >>>
     >>> fig, ax = plt.subplots()
-    >>> g.plot(plot_eigenvalues=True, ax=ax)
+    >>> g.plot(eigenvalues=True, ax=ax)
     >>> _ = ax.set_title('Filter frequency response')
 
 The filter is plotted along all the spectrum of the graph. The black crosses

pygsp/__init__.py

@@ -30,5 +30,20 @@
 
 _utils.import_modules(__all__[::-1], 'pygsp', 'pygsp')
 
+# Users only call the plot methods from the objects.
+# It's thus more convenient for them to have the doc there.
+# But it's more convenient for developers to have the doc alongside the code.
+try:
+    filters.Filter.plot.__doc__ = plotting._plot_filter.__doc__
+    graphs.Graph.plot.__doc__ = plotting._plot_graph.__doc__
+    graphs.Graph.plot_signal.__doc__ = plotting._plot_signal.__doc__
+    graphs.Graph.plot_spectrogram.__doc__ = plotting._plot_spectrogram.__doc__
+except AttributeError:
+    # For Python 2.7.
+    filters.Filter.plot.__func__.__doc__ = plotting._plot_filter.__doc__
+    graphs.Graph.plot.__func__.__doc__ = plotting._plot_graph.__doc__
+    graphs.Graph.plot_signal.__func__.__doc__ = plotting._plot_signal.__doc__
+    graphs.Graph.plot_spectrogram.__func__.__doc__ = plotting._plot_spectrogram.__doc__
+
 __version__ = '0.5.1'
 __release_date__ = '2017-12-15'

pygsp/data/readme_example_filter.png

@@ -533,10 +533,9 @@ def can_dual_func(g, n, x):
 
         return Filter(self.G, kernels)
 
-    def plot(self, **kwargs):
-        r"""Plot the filter bank's frequency response.
-
-        See :func:`pygsp.plotting.plot_filter`.
-        """
-        from pygsp import plotting
-        plotting.plot_filter(self, **kwargs)
+    def plot(self, n=500, eigenvalues=None, sum=None, title='', save=None,
+             ax=None, **kwargs):
+        r"""Docstring overloaded at import time."""
+        from pygsp.plotting import _plot_filter
+        _plot_filter(self, n=n, eigenvalues=eigenvalues, sum=sum, title=title,
+                     save=save, ax=ax, **kwargs)

pygsp/data/readme_example.png renamed to pygsp/data/readme_example_graph.png

@@ -16,7 +16,7 @@ class Airfoil(Graph):
     >>> G = graphs.Airfoil()
     >>> fig, axes = plt.subplots(1, 2)
     >>> _ = axes[0].spy(G.W, markersize=0.5)
-    >>> G.plot(show_edges=True, ax=axes[1])
+    >>> G.plot(edges=True, ax=axes[1])
 
     """