Merge pull request #130 from jaidevd/jd-tutorial

DOC: Add examples

doc/Makefile

@@ -4,9 +4,11 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
+SPHINXAPIDOC  = sphinx-apidoc
 PAPER         =
 BUILDDIR      = _build
 EXAMPLEDIR    = auto_examples
+APIREF        = apiref
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -50,8 +52,10 @@ help:
 clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf $(EXAMPLEDIR)/*
+	rm -rf $(APIREF)/*
 
 html:
+	$(SPHINXAPIDOC) -o apiref ../tftb
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

doc/_templates/localtoc.html

@@ -0,0 +1,10 @@
+{% if pagename != 'index' %}
+
+    {%- if display_toc %}
+        <h4 class="sidebar-box-heading">Contents</h4>
+        <div class="well sidebar-box toc">
+            {{ toc|replace('<ul>', '<ul class="nav nav-list">') }}
+        </div>
+    {%- endif %}
+
+{% endif %}

doc/_templates/navigation.html

@@ -0,0 +1,22 @@
+<h4 class="sidebar-box-heading">{{ _('Navigation') }}</h4>
+<div class="well sidebar-box">
+    <ul class="nav nav-list">
+        <li><a href="{{ pathto(master_doc) }}">Documentation Home</a></li>
+    </ul>
+</div>
+{%- if prev %}
+    <h4 class="sidebar-box-heading">{{ _('Previous topic') }}</h4>
+    <div class="well sidebar-box">
+        <ul class="nav nav-list">
+            <li><a href="{{ prev.link|e }}" title="{{ _('previous chapter') }}">{{ prev.title }}</a></li>
+        </ul>
+    </div>
+{%- endif %}
+{%- if next %}
+    <h4 class="sidebar-box-heading">{{ _('Next topic') }}</h4>
+    <div class="well sidebar-box">
+        <ul class="nav nav-list">
+            <li><a href="{{ next.link|e }}" title="{{ _('next chapter') }}">{{ next.title }}</a></li>
+        </ul>
+    </div>
+{%- endif %}

doc/apiref/tftb.generators.rst

@@ -1,6 +1,13 @@
 tftb.generators package
 =======================
 
+Subpackages
+-----------
+
+.. toctree::
+
+    tftb.generators.tests
+
 Submodules
 ----------
 

doc/apiref/tftb.generators.tests.rst

@@ -0,0 +1,62 @@
+tftb.generators.tests package
+=============================
+
+Submodules
+----------
+
+tftb.generators.tests.test_amplitude_modulations module
+-------------------------------------------------------
+
+.. automodule:: tftb.generators.tests.test_amplitude_modulations
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+tftb.generators.tests.test_analytic_signals module
+--------------------------------------------------
+
+.. automodule:: tftb.generators.tests.test_analytic_signals
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+tftb.generators.tests.test_frequency_modulations module
+-------------------------------------------------------
+
+.. automodule:: tftb.generators.tests.test_frequency_modulations
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+tftb.generators.tests.test_misc module
+--------------------------------------
+
+.. automodule:: tftb.generators.tests.test_misc
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+tftb.generators.tests.test_noise module
+---------------------------------------
+
+.. automodule:: tftb.generators.tests.test_noise
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+tftb.generators.tests.test_utils module
+---------------------------------------
+
+.. automodule:: tftb.generators.tests.test_utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: tftb.generators.tests
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/apiref/tftb.processing.rst

@@ -20,6 +20,14 @@ tftb.processing.ambiguity module
     :undoc-members:
     :show-inheritance:
 
+tftb.processing.base module
+---------------------------
+
+.. automodule:: tftb.processing.base
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 tftb.processing.cohen module
 ----------------------------
 

doc/apiref/tftb.rst

@@ -13,14 +13,6 @@ Subpackages
 Submodules
 ----------
 
-tftb.transutils module
-----------------------
-
-.. automodule:: tftb.transutils
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 tftb.utils module
 -----------------
 

doc/apiref/tftb.tests.rst

@@ -12,42 +12,10 @@ tftb.tests.base module
     :undoc-members:
     :show-inheritance:
 
-tftb.tests.test_amplitude_modulations module
---------------------------------------------
-
-.. automodule:: tftb.tests.test_amplitude_modulations
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-tftb.tests.test_analytic_signals module
----------------------------------------
-
-.. automodule:: tftb.tests.test_analytic_signals
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-tftb.tests.test_frequency_modulations module
---------------------------------------------
-
-.. automodule:: tftb.tests.test_frequency_modulations
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-tftb.tests.test_misc module
----------------------------
-
-.. automodule:: tftb.tests.test_misc
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-tftb.tests.test_noise module
+tftb.tests.test_utils module
 ----------------------------
 
-.. automodule:: tftb.tests.test_noise
+.. automodule:: tftb.tests.test_utils
     :members:
     :undoc-members:
     :show-inheritance:

doc/conf.py

@@ -159,7 +159,9 @@
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+   '**': ['navigation.html', 'localtoc.html', 'sourcelink.html', 'searchbox.html'],
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

doc/index.rst

@@ -11,6 +11,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   introduction
    auto_gallery
    api
 

doc/introduction.rst

@@ -0,0 +1,45 @@
+======================
+Introduction to PyTFTB
+======================
+
+About PyTFTB
+------------
+
+The PyTFTB project began as a Python implementation of the
+`TFTB toolbox <http://tftb.nongnu.org/>`_ developed by François Auger,
+Olivier Lemoine, Paulo Gonçalvès and Patrick Flandrin. While the Python
+implementation (henceforth referred to as PyTFTB) and the MATLAB implementation
+(henceforth referred to as TFTB) are similar in the core algorithms and the
+basic code organization, the very nature of the Python programming language
+has motivated a very different approach in architecture of PyTFTB (differences
+between the two packages have been discussed in detail in the next section).
+Thus, someone who is familiar with TFTB should find the PyTFTB API comfortably
+within grasp, and someone who is beginning with PyTFTB should find it a fully
+self contained library to use.
+
+Comparison of TFTB and PyTFTB
+-----------------------------
+
+TFTB is broadly a collection of MATLAB functions and demos that demonstrate the use of these functions.
+A detailed reference of these functions can be found `here <http://tftb.nongnu.org/refguide.pdf>`_. The fact that
+Python is a general purpose programming language affords the users and the developers a lot of freedom, especially with
+regard to code reuse and interfacing. The important differences in implementation are as follows:
+
+1. PyTFTB makes heavy use of Python's object oriented design. This allows for code reuse and interfacing. Algorithms
+that are very closely related to each other can inherit from thew same base class and reuse each others methods.
+
+2. In TFTB, visualization of time frequency distributions is handled by dedicated functions like `tfrview` and `tfrqview`
+whereas in PyTFTB, they are tightly coupled to the specific representation being computed.
+
+3. PyTFTB is heavily dependent on the SciPy stack - especially the NumPy and the SciPy libraries. Whichever piece of
+code can be delegated to these libraries is delegated to them.
+
+Quick Start
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   quickstart/intro_examples_1.rst
+   quickstart/intro_examples_2.rst
+

doc/quickstart/intro_examples_1.rst

@@ -0,0 +1,91 @@
+======================================
+Example 1: Linear Frequency Modulation
+======================================
+
+Let us consider first a signal with constant amplitude, and with a linear frequency modulation - i.e. a signal such that
+its amplitude remains constant, but frequency increases linearly with time - varying from 0 to 0.5 in
+normalized frequency (ratio of the frequency in Hertz to the sampling frequency, with respect to the Shannon sampling
+theorem). This signal is called a chirp, and as its frequency content is varying with time, it is a non-stationary
+signal. To obtain such a signal, we can use the function ``tftb.generators.fmlin``, which generates a linear frequency
+modulation.
+
+    >>> from tftb.generators import amgauss, fmlin
+    >>> import matplotlib.pyplot as plt
+    >>> z = amgauss(128, 50, 40) * fmlin(128, 0.05, 0.3, 50)[0]
+    >>> plt.plot(real(z))
+    >>> plt.title("Linear Frequency Modulation")
+    >>> plt.show()
+
+    .. plot:: docstring_plots/generators/frequency_modulated/fmlin.py
+
+From this time-domain representation, it is difficult to say what kind of modulation is contained in this signal:
+what are the initial and final frequencies, is it a linear, parabolic, hyperbolic... frequency modulation?
+
+If we now consider the energy spectrum of the signal ``z`` by squaring the modulus of its Fourier transform
+(using the ``numpy.fft.fft`` function):
+
+    >>> import numpy as np
+    >>> dsp1 = np.fft.fftshift(np.abs(np.fft.fft(z)) ** 2)
+    >>> plt.plot(np.arange(-64, 64, dtype=float) / 128.0, dsp1)
+    >>> plt.xlim(-0.5, 0.5)
+    >>> plt.title('Spectrum')
+    >>> plt.ylabel('Squared modulus')
+    >>> plt.xlabel('Normalized Frequency')
+    >>> plt.grid()
+    >>> plt.show()
+
+    .. plot:: auto_examples/plot_1_3_1_chirp_spectrum.py
+
+we still can not say, from this plot, anything about the evolution in time of the frequency content. This is due to the
+fact that the Fourier transform is a decomposition on complex exponentials, which are of infinite duration and
+completely unlocalized in time. Time information is in fact encoded in the phase of the Fourier transform
+(which is simply ignored by the energy spectrum), but their interpretation is not straightforward and their direct
+extraction is faced with a number of difficulties such as phase unwrapping. In order to have a more informative
+description of such signals, it would be better to directly represent their frequency content while still keeping the
+time description parameter. This is precisely the aim of time-frequency analysis. To illustrate this, let us try the
+Wigner-Ville distribution on this signal.
+
+    >>> from tftb.processing import WignerVilleDistribution
+    >>> wvd = WignerVilleDistribution(z)
+    >>> wvd.run()
+    >>> wvd.plot(kind='contour', extent=[0, n_points, fmin, fmax])
+
+    .. plot:: auto_examples/plot_1_3_1_chirp_wv.py
+
+we can see that the linear progression of the frequency with time, from 0 to 0.5, is clearly shown.
+
+If we now add some complex white gaussian noise on this signal,
+
+    >>> from tftb.generators import sigmerge, noisecg
+    >>> noisy_signal = sigmerge(z, noisecg(128), 0)
+    >>> plt.plot(np.real(noisy_signal))
+    >>> plt.xlim(0, 128)
+    >>> plt.title('Noisy chirp')
+    >>> plt.ylabel('Real Part')
+    >>> plt.xlabel('Time')
+    >>> plt.grid()
+    >>> plt.show()
+
+    .. plot:: auto_examples/plot_1_3_1_noisy_chirp.py
+
+and consider the spectrum of it,
+
+    >>> dsp1 = np.fft.fftshift(np.abs(np.fft.fft(noisy_signal)) ** 2)
+    >>> plt.plot(np.arange(-64, 64, dtype=float) / 128.0, dsp1)
+    >>> plt.xlim(-0.5, 0.5)
+    >>> plt.title('Spectrum of Noisy Chirp')
+    >>> plt.ylabel('Squared modulus')
+    >>> plt.xlabel('Normalized Frequency')
+    >>> plt.grid()
+    >>> plt.show()
+
+    .. plot:: auto_examples/plot_1_3_1_noisy_chirp_spectrum.py
+
+it is worse than before to interpret these plots. On the other hand, the Wigner-Ville distribution still show quite
+clearly the linear progression of the frequency with time.
+
+    >>> wvd = WignerVilleDistribution(noisy_signal)
+    >>> wvd.run()
+    >>> wvd.plot(kind='contour')
+
+    .. plot:: auto_examples/plot_1_3_1_noisy_chirp_wv.py