Merge branch 'release/v0.5.1'

EtienneCmb · Jun 27, 2017 · 4060a32 · 4060a32
2 parents 006b2fe + 95f0479
commit 4060a32
Show file tree

Hide file tree

Showing 13 changed files with 330 additions and 56 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -60,9 +60,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.5.0'
+version = '0.5.1'
 # The full version, including alpha/beta/rc tags.
-release = '0.5.0'
+release = '0.5.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,33 +6,33 @@
 .. image:: https://codecov.io/gh/EtienneCmb/tensorpac/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/EtienneCmb/tensorpac
 
+.. image:: https://badge.fury.io/py/Tensorpac.svg
+    :target: https://badge.fury.io/py/Tensorpac
+
 Tensorpac
 #########
 
 Tensorpac is an Python open-source toolbox for computing Phase-Amplitude Coupling (PAC) using tensors and parallel computing. On top of that, we designed a modular implementation with a relatively large amount of parameters.
 We provide a set of `examples <https://github.com/EtienneCmb/tensorpac/tree/master/examples>`_.
 
-This package was developped in collaboration with **Juan L.P. Soto**
-
 .. figure::  picture/tp.png
    :align:   center
 
 Installation:
 *************
 
-Tensorpac is only based on NumPy and use `Joblib <https://pythonhosted.org/joblib/>`_ for parallel computing. For the installation, in a terminal run :
+Tensorpac is based on NumPy, SciPy and use `Joblib <https://pythonhosted.org/joblib/>`_ for parallel computing. For the installation, in a terminal run :
 
 .. code-block:: bash
 
-    git clone https://github.com/EtienneCmb/tensorpac.git tensorpac
-    cd tensorpac
-    pip setup.py install
+    pip install tensorpac
 
 What's new?
 ***********
 
-* New in version v0.4
+* New in version v0.5.1
 
+    * Compute and plot preferred-phase
     * Bug fixing
 
 Todo list
@@ -52,7 +52,6 @@ Contents:
 .. toctree::
    :maxdepth: 3
 
-   tutorial
    methods
    pyfcn
    utils

diff --git a/docs/source/methods.rst b/docs/source/methods.rst
@@ -1,7 +1,7 @@
 .. _Methods:
 
-Methods
-=======
+Implemented methods
+===================
 
 Starting from fresh data, the first thing that need to be assessed is extracting the phase and the amplitude in several frequency bands. There is two ways to doing it :
 
@@ -57,10 +57,10 @@ The second digit refer to the method for evaluating surrogates :
 
 [`Surrogate methods script <https://github.com/EtienneCmb/tensorpac/blob/master/examples/5_CompareSurrogatesMethods.py>`_]
 
-.. figure::  picture/6_normmeth.png
+.. figure::  picture/5_surrometh.png
    :align:   center
 
-   `Surrogate methods comparison <https://github.com/EtienneCmb/tensorpac/blob/master/docs/source/picture/6_normmeth.png>`_.
+   `Surrogate methods comparison <https://github.com/EtienneCmb/tensorpac/blob/master/docs/source/picture/5_surrometh.png>`_.
 
 Normalization methods
 ~~~~~~~~~~~~~~~~~~~~~
@@ -88,8 +88,8 @@ Example
 * idpac = (5, 2, 1) => PS + Swap amplitude time blocks + Substraction of the mean of surrogates
 
 
-Link with publications
-----------------------
+.. Link with publications
+.. ----------------------
 
-* Canolty, 2006 : idpac = ()
-* Tort, 2010 : idpac = ()
+.. * Canolty, 2006 : idpac = ()
+.. * Tort, 2010 : idpac = ()
diff --git a/docs/source/picture/PP_planningVsExec.png b/docs/source/picture/PP_planningVsExec.png
diff --git a/docs/source/picture/fminfmax.png b/docs/source/picture/fminfmax.png
diff --git a/docs/source/pyfcn.rst b/docs/source/pyfcn.rst
@@ -3,11 +3,12 @@
 Python functions
 =================
 
-The first thing to do is to define a `pacobj`. Then, from this objects, you can use one of the three following methods :
+The first thing to do is to define a `pacobj`. Then, from this objects, you can use one of the following methods :
 
 * :ref:`filtdata` : use this method to extract the phase and the amplitude.
 * :ref:`pacfilt` : if you already extracted your phase and amplitude, use this method to compute pac directly on it. 
 * :ref:`filtpac` : this is the all in one method. Starting from fresh data, this method will extract phase and amplitude and return the PAC estimation.
+* :ref:`pp` : compute the preferred-phase.
 
 .. _pacobj:
 
@@ -43,6 +44,15 @@ For those who already have filtered and computed the phase and amplitude, use th
 Filter then compute PAC
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Finally, use the following method to filter and compute the PAC directly.
+Use the following method to filter and compute the PAC directly.
 
-.. automethod:: tensorpac.pac.Pac.filterfit
+.. automethod:: tensorpac.pac.Pac.filterfit
+
+.. _pp:
+
+Preferred-phase
+~~~~~~~~~~~~~~~
+
+Compute the preferred-phase (PP, see `this PP example <https://github.com/EtienneCmb/tensorpac/tree/master/examples/13_PreferredPhase.py>`_). 
+
+.. automethod:: tensorpac.pac.Pac.pp
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
diff --git a/docs/source/utils.rst b/docs/source/utils.rst
@@ -3,10 +3,14 @@
 Utils
 =====
 
+Generate artificially coupled signals
+-------------------------------------
+.. autofunction:: tensorpac.utils.PacSignals
+
 Generate phase and amplitude vectors
 ------------------------------------
 .. autofunction:: tensorpac.utils.PacVec
 
-Generate artificially coupled signals
--------------------------------------
-.. autofunction:: tensorpac.utils.PacSignals
+Generate triangular vectors
+---------------------------
+.. autofunction:: tensorpac.utils.PacTriVec
diff --git a/docs/source/visu.rst b/docs/source/visu.rst
@@ -3,7 +3,14 @@
 Visualization
 =============
 
-If matplotlib is install on your system, the main Pac class also include a comodulogram plotting method that rely on Matplotlib. This script is also present in the `example <https://github.com/EtienneCmb/tensorpac/blob/master/examples/9_PlayWithColors.py>`_ folder.
+If matplotlib is install on your system, the main Pac class also include several plotting functions :
+
+* :ref:`pltcomo` : comodulogram plot, for finding the coupling location *PAC(phase, amplitude)*
+* :ref:`plttri` : triangular plot for finding where each band [Start, Stop] and the bandwidth *PAC(Starting frequency, Ending frequency)*
+* :ref:`pltpp` : polar plot for the preferred-phase representation *PP(phase, binned amplitude)*
+
+
+plotting method that rely on Matplotlib. This script is also present in the `example <https://github.com/EtienneCmb/tensorpac/blob/master/examples/9_PlayWithColors.py>`_ folder.
 
 Code example
 ------------
@@ -70,14 +77,35 @@ Code example
 
     plt.show()
 
+
+.. _pltcomo:
+
+Comodulogram
+------------
+
 .. figure::  picture/9_plot.png
    :align:   center
 
-   `Plotting comodulogram <https://github.com/EtienneCmb/tensorpac/blob/master/docs/source/picture/9_plot.png>`_
-
-Comodulogram method description
--------------------------------
+   Comodulogram forms.
 
 .. automethod:: tensorpac.pac.Pac.comodulogram
 
+.. _plttri:
+
+Triangular plot
+---------------
+
+.. figure::  picture/fminfmax.png
+   :align:   center
+
+.. automethod:: tensorpac.pac.Pac.triplot
+
+.. _pltpp:
+
+Polar plot
+----------
+
+.. figure::  picture/PP_planningVsExec.png
+   :align:   center
 
+.. automethod:: tensorpac.pac.Pac.triplot
diff --git a/examples/13_PreferredPhase.py b/examples/13_PreferredPhase.py
@@ -0,0 +1,68 @@
+"""This example illustrate hox to find the preferred-phase (PP).
+
+First, the amplitude is binned according to phase slices (360°/nbins). Then,
+the PP is defined as the phase where the amplitude is maximum.
+"""
+import numpy as np
+import matplotlib.pyplot as plt
+from tensorpac import PacSignals, Pac
+
+plt.style.use('seaborn-poster')
+
+# Generate 100 datasets with a [5, 7]<->[90, 100]hz coupling :
+sf = 1024.
+ndatasets = 100
+data, time = PacSignals(fpha=[5, 7], famp=[95, 105], ndatasets=ndatasets,
+                        sf=sf, noise=3, chi=.7, npts=2000)
+
+
+# Define a Pac object. Here, we are not going to use the idpac variable :
+p = Pac(fpha=[5, 7], famp=(60, 200, 10, 1))
+
+# Extract the phase and the amplitude :
+pha = p.filter(sf, data, axis=1, ftype='phase')
+amp = p.filter(sf, data, axis=1, ftype='amplitude')
+
+# Introduce a 2*pi/2 phase shift (equivalent to adding a 90° shift) :
+pha += np.pi/2
+
+# Now, compute the PP :
+ambin, pp, vecbin = p.pp(pha, amp, axis=2, nbins=72)
+
+# Reshape the PP to be (ndatasets, namp) :
+pp = np.squeeze(pp).T
+
+# Reshape the amplitude to be (nbins, namp, ndatasets) and take the mean across
+# datasets :
+ambin = np.squeeze(ambin).mean(-1)
+
+# plt.figure(figsize=(20, 35))
+# Plot the prefered phase :
+plt.subplot(221)
+plt.pcolormesh(p.yvec, np.arange(100), np.rad2deg(pp), cmap='Spectral_r')
+cb = plt.colorbar()
+plt.clim(vmin=-180., vmax=180.)
+plt.axis('tight')
+plt.xlabel('Amplitude center frequency (Hz)')
+plt.ylabel('Ndatasets')
+plt.title("PP for each dataset and for several amplitudes.\n100hz amplitudes"
+          " are phase locked to 90° (<=> pi/2)")
+cb.set_label('PP (in degrees)')
+
+# Then, we show  the histogram corresponding to an 100he amplitude :
+idx100 = np.abs(p.yvec - 100.).argmin()
+plt.subplot(222)
+h = plt.hist(pp[:, idx100], color='#ab4642')
+plt.xlim((-np.pi, np.pi))
+plt.xlabel('PP')
+plt.title('PP across trials for the 100hz amplitude')
+plt.xticks([-np.pi, -np.pi/2, 0, np.pi/2, np.pi])
+plt.gca().set_xticklabels([r"$-\pi$", r"$-\frac{\pi}{2}$", "$0$",
+                          r"$\frac{\pi}{2}$", r"$\pi$"])
+
+p.polar(ambin.T, vecbin, p.yvec, cmap='Spectral_r', interp=.1, subplot=212,
+        cblabel='Amplitude bins')
+
+# plt.savefig('pp.png', dpi=300, bbox_inches='tight')
+
+p.show()
diff --git a/setup.py b/setup.py
@@ -6,7 +6,7 @@
 from pip.req import parse_requirements
 from optparse import Option
 
-__version__ = "0.5.0"
+__version__ = "0.5.1"
 NAME = 'Tensorpac'
 AUTHOR = "Etienne Combrisson"
 MAINTAINER = "Etienne Combrisson"