From cbb85e12c5d7e6414c1bdffb089a562f1e974e19 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C3=ABl=20Defferrard?= <michael.defferrard@epfl.ch>
Date: Mon, 2 Apr 2018 16:33:04 +0200
Subject: [PATCH] doc: examples of filter approximations

---
 pygsp/filters/__init__.py       |  1 +
 pygsp/filters/approximations.py | 20 ++++++++++++++++++++
 pygsp/filters/filter.py         | 32 +++++++++++++++++++++++++++++---
 3 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/pygsp/filters/__init__.py b/pygsp/filters/__init__.py
index 39726683..35d628e4 100644
--- a/pygsp/filters/__init__.py
+++ b/pygsp/filters/__init__.py
@@ -20,6 +20,7 @@
     Filter.synthesize
     Filter.compute_frame
     Filter.estimate_frame_bounds
+    Filter.approximate
     Filter.plot
     Filter.localize
 
diff --git a/pygsp/filters/approximations.py b/pygsp/filters/approximations.py
index 0af87c13..081f79ad 100644
--- a/pygsp/filters/approximations.py
+++ b/pygsp/filters/approximations.py
@@ -38,6 +38,26 @@ class Chebyshev(Filter):
     order : int
         Polynomial order.
 
+    Examples
+    --------
+
+    Plot the basis formed by the first K Chebyshev polynomials:
+
+    >>> import matplotlib.pyplot as plt
+    >>> fig, ax = plt.subplots(1, 1)
+    >>>
+    >>> G = graphs.Ring()
+    >>> G.estimate_lmax()
+    >>>
+    >>> K = 5  # Polynomials of order up to K.
+    >>>
+    >>> coefficients = np.identity(K)
+    >>> f = filters.Chebyshev(G, coefficients)
+    >>> f.plot(sum=False, eigenvalues=False, ax=ax)
+    >>>
+    >>> _ = ax.set_title('Chebysev polynomials')
+    >>> _ = ax.legend(['order {}'.format(order) for order in range(K)])
+
     """
 
     def __init__(self, G, coefficients):
diff --git a/pygsp/filters/filter.py b/pygsp/filters/filter.py
index 376402b9..c30e744a 100644
--- a/pygsp/filters/filter.py
+++ b/pygsp/filters/filter.py
@@ -100,7 +100,7 @@ def _evaluate(self, x, _):
         return y
 
     def approximate(self, method, **kwargs):
-        r"""Returns a filter which approximates this filter.
+        r"""Return a filter which approximates this filter.
 
         While approximations might loose accuracy, they allow for much faster
         computations.
@@ -114,7 +114,33 @@ def approximate(self, method, **kwargs):
 
         Examples
         --------
-        TODO: approx plot from notebook (needs new plotting)
+
+        Approximate a filter with Chebyshev polynomials of various orders:
+
+        >>> import matplotlib.pyplot as plt
+        >>> fig, ax = plt.subplots(1, 1)
+        >>>
+        >>> G = graphs.Ring()
+        >>> G.compute_fourier_basis()
+        >>> f1 = filters.Heat(G)
+        >>> f1.plot(eigenvalues=True, linewidth=3, label='continuous', ax=ax)
+        >>>
+        >>> for order in range(1, 5):
+        ...     f2 = f1.approximate('Chebyshev', order=order)
+        ...     l = 'Chebyshev order {}'.format(order)
+        ...     f2.plot(eigenvalues=False, label=l, linestyle='dashed', ax=ax)
+        >>>
+        >>> _ = ax.set_title('Approximation for various polynomial orders')
+        >>> _ = ax.legend()
+
+        Approximate a filterbank with Chebyshev polynomials:
+
+        >>> G = graphs.Ring()
+        >>> G.compute_fourier_basis()
+        >>> f1 = filters.Itersine(G)
+        >>> f2 = f1.approximate('Chebyshev', order=20)
+        >>> f1.plot(title='Continuous filterbank')
+        >>> f2.plot(title='Approximated filterbank')
 
         """
         from . import approximations
@@ -173,7 +199,7 @@ def filter(self, s, method=None, order=30):
         s : ndarray
             Graph signals, a tensor of shape ``(N_NODES, N_SIGNALS,
             N_FEATURES)``, where ``N_NODES`` and ``N_SIGNALS`` are the number
-            of nodes and signals of the signal tensor that pas passed in, and
+            of nodes and signals of the signal tensor that was passed in, and
             ``N_FEATURES`` is either 1 (synthesis) or the number of filters in
             the filter bank (analysis).