Merge pull request #98 from liuzhenqi77/surf-plot

[DOC] Added example for plotting on fsaverage surface

Author: rmarkello

docs/installation.rst

@@ -23,3 +23,88 @@ Alternatively, you can install ``netneurotools`` directly from PyPi with:
 .. code-block:: bash
 
     pip install netneurotools
+
+Optional installation for surface plotting
+------------------------------------------
+
+In order to use surface plotting functionality like
+:py:func:`netneurotools.plotting.plot_fsaverage`, you will need a working
+``vtk``/``mayavi``/``pysurfer`` installation. These can generally be installed 
+with the following command:
+
+.. code-block: bash
+
+    pip install vtk mayavi pysurfer
+
+However, we include instructions below for installing the bleeding-edge version 
+of the dependencies. Note: if you already have a working ``mayavi``/``pysurfer`` 
+installation, there is generally no need to follow these instructions!
+
+-  Install Qt
+
+   -  Installing Jupyterlab using conda (``conda install jupyterlab``)
+      should automatically install the required qt/pyqt packages.
+   -  If otherwise, using ``pip install PyQt5`` should also work as
+      suggested by
+      `here <http://docs.enthought.com/mayavi/mayavi/installation.html#latest-stable-release>`__
+      and `here <https://github.com/enthought/mayavi#installation>`__
+   -  If not working, search for the error prompts like
+      `this <https://askubuntu.com/questions/308128/failed-to-load-platform-plugin-xcb-while-launching-qt5-app-on-linux-without>`__.
+
+-  Install VTK
+
+   -  Official wheels for the latest VTK9 are available for download
+      `here <https://vtk.org/download/>`__.
+   -  For Python>=3.9, official wheel is `not available at the
+      moment <https://discourse.vtk.org/t/python-3-9/4369/3>`__.
+      Following
+      `here <https://docs.pyvista.org/extras/building_vtk.html>`__ and
+      `here <https://gitlab.kitware.com/vtk/vtk/-/blob/master/Documentation/dev/build.md#python-wheels>`__,
+      it’s possible to build the wheel. See the example code below.
+
+.. code:: bash
+
+   git clone https://github.com/Kitware/VTK
+   cd VTK
+
+   mkdir build
+   cd build
+   PYBIN=<PATH TO YOUR PYTHON EXECUTABLE>
+   cmake -GNinja -DVTK_BUILD_TESTING=OFF -DVTK_WHEEL_BUILD=ON -DVTK_PYTHON_VERSION=3 -DVTK_WRAP_PYTHON=ON -DPython3_EXECUTABLE=$PYBIN ../
+
+   # optionally, apt install ninja
+   ninja
+   $PYBIN setup.py bdist_wheel
+
+   # to install
+   pip install dist/vtk-*.whl
+
+-  Install mayavi
+
+   -  Install from source
+      ``pip install git+https://github.com/enthought/mayavi.git``
+
+-  Install pysurfer
+
+   -  Install from source
+      ``pip install git+https://github.com/nipy/PySurfer.git``
+
+-  Install netneurotools
+
+   -  Install from source
+      ``pip install git+https://github.com/netneurolab/netneurotools.git``
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+-  Error related to ``from tvtk.vtk_module import VTK_MAJOR_VERSION``
+
+   -  `Currently not
+      fixed <https://github.com/enthought/mayavi/issues/939#issuecomment-747266625>`__
+   -  Temporary workaround: adding ``VTK_MAJOR_VERSION = 9`` to
+      ``mayavi/tvtk/vtk_module.py``
+
+-  Error related to GLX
+
+   -  Try ``glxgears`` or ``glxinfo``
+   -  Check display driver compatibility

netneurotools/plotting.py

@@ -416,6 +416,34 @@ def plot_fsaverage(data, *, lhannot, rhannot, order='lr', mask=None,
     -------
     brain : surfer.Brain
         Plotted PySurfer brain
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from netneurotools.datasets import fetch_cammoun2012, \
+                                           fetch_schaefer2018
+    >>> from netneurotools.plotting import plot_fsaverage
+
+    Plotting with the Cammoun 2012 parcellation we specify `order='RL'` because
+    many of the Lausanne connectomes have data for the right hemisphere before
+    the left hemisphere.
+
+    >>> values = np.random.rand(219)
+    >>> scale = 'scale125'
+    >>> cammoun = fetch_cammoun2012('fsaverage', verbose=False)[scale]
+    >>> plot_fsaverage(values, order='RL',
+    ...                lhannot=cammoun.lh, rhannot=cammoun.rh) # doctest: +SKIP
+
+    Plotting with the Schaefer 2018 parcellation we can use the default
+    parameter for `order`:
+
+    >>> values = np.random.rand(400)
+    >>> scale = '400Parcels7Networks'
+    >>> schaefer = fetch_schaefer2018('fsaverage', verbose=False)[scale]
+    >>> plot_fsaverage(values,
+    ...                lhannot=schaefer.lh,
+    ...                rhannot=schaefer.rh)  # doctest: +SKIP
+
     """
 
     subject_id, subjects_dir = _get_fs_subjid(subject_id, subjects_dir)