Surface plots

.gitignore

@@ -37,3 +37,6 @@ tags
 venv/
 
 doc/themes/nilearn/static/jquery.js
+.vscode/
+examples/results/
+examples/**/*.pdf

doc/modules/reference.rst

@@ -344,6 +344,7 @@ the :ref:`user guide <user_guide>` for more information and usage examples.
    plot_surf_roi
    plot_surf_contours
    plot_surf_stat_map
+   plot_img_on_surf
    view_surf
    view_img_on_surf
    view_connectome

doc/whats_new.rst

@@ -25,7 +25,9 @@ NEW
   as a "Power plot" or a "grayplot"), for visualizing global patterns in
   4D functional data over time.
 - New plotting function
-  :func:`nilearn.plotting.plot_markers` shows network nodes (markers) on a glass
+  :func:`nilearn.plotting.plot_img_on_surf` generates multiple views of
+  :func:`nilearn.plotting.plot_surf_stat_map` in a single figure.
+- :func:`nilearn.plotting.plot_markers` shows network nodes (markers) on a glass
   brain template and color code them according to provided nodal measure (i.e.
   connection strength). This function will replace
   :func:`nilearn.plotting.plot_connectome_strength`.
@@ -354,7 +356,7 @@ NEW
   when using the `mask_strategy="template"` option for brains in MNI space.
 - New brain development fMRI dataset fetcher
   :func:`nilearn.datasets.fetch_development_fmri` can be used to download
-  movie-watching data in children and adults; a light-weight dataset 
+  movie-watching data in children and adults; a light-weight dataset
   implemented for teaching and usage in the examples.
 - New example in `examples/05_advanced/plot_age_group_prediction_cross_val.py`
   to compare methods for classifying subjects into age groups based on
@@ -377,8 +379,8 @@ Changes
 
 - All the connectivity examples are changed from ADHD to brain development
   fmri dataset.
-- Examples plot_decoding_tutorial, plot_haxby_decoder, 
-  plot_haxby_different_estimators, plot_haxby_full_analysis, plot_oasis_vbm now 
+- Examples plot_decoding_tutorial, plot_haxby_decoder,
+  plot_haxby_different_estimators, plot_haxby_full_analysis, plot_oasis_vbm now
   use :class:`nilearn.decoding.Decoder` and :class:`nilearn.decoding.DecoderRegressor`
   instead of sklearn SVC and SVR.
 

examples/01_plotting/plot_3d_map_to_surface_projection.py

@@ -104,9 +104,22 @@
                             threshold=1., bg_map=big_fsaverage.sulc_right)
 
 
+##############################################################################
+# Plot multiple views of the 3D volume on a surface
+# -------------------------------------------------
+#
+# *plot_img_on_surf* takes a statistical map and projects it onto a surface.
+# It supports multiple choices of orientations, and can plot either one or both
+# hemispheres. If no *surf_mesh* is given, *plot_img_on_surf* projects the
+# images onto `FreeSurfer <https://surfer.nmr.mgh.harvard.edu/>`_\'s
+# fsaverage5.
+
+plotting.plot_img_on_surf(stat_img,
+                          views=['lateral', 'medial'],
+                          hemispheres=['left', 'right'],
+                          colorbar=True)
 plotting.show()
 
-
 ##############################################################################
 # 3D visualization in a web browser
 # ---------------------------------

nilearn/plotting/__init__.py

@@ -50,15 +50,16 @@ def _set_mpl_backend():
 from .html_stat_map import view_img
 from .html_connectome import view_connectome, view_markers
 from .surf_plotting import (plot_surf, plot_surf_stat_map, plot_surf_roi,
-                            plot_surf_contours)
+                            plot_img_on_surf, plot_surf_contours)
 
 __all__ = ['cm', 'plot_img', 'plot_anat', 'plot_epi',
            'plot_roi', 'plot_stat_map', 'plot_glass_brain',
            'plot_markers', 'plot_connectome', 'plot_prob_atlas',
            'find_xyz_cut_coords', 'find_cut_slices',
            'show', 'plot_matrix', 'view_surf', 'view_img_on_surf',
            'view_img', 'view_connectome', 'view_markers',
-           'find_parcellation_cut_coords', 'find_probabilistic_atlas_cut_coords',
+           'find_parcellation_cut_coords',
+           'find_probabilistic_atlas_cut_coords',
            'plot_surf', 'plot_surf_stat_map', 'plot_surf_roi',
-           'plot_connectome_strength', 'plot_carpet', 'plot_surf_contours'
-           ]
+           'plot_img_on_surf', 'plot_connectome_strength', 'plot_carpet',
+           'plot_surf_contours']

nilearn/plotting/html_surface.py

@@ -5,11 +5,12 @@
 import matplotlib as mpl
 from matplotlib import cm as mpl_cm
 
-from .._utils.niimg_conversions import check_niimg_3d
-from .. import datasets, surface
+from nilearn._utils.niimg_conversions import check_niimg_3d
+from nilearn import surface
+from nilearn import datasets
 from nilearn.reporting import HTMLDocument
-from . import cm
-from .js_plotting_utils import (
+from nilearn.plotting import cm
+from nilearn.plotting.js_plotting_utils import (
     colorscale, mesh_to_plotly, get_html_template, add_js_lib,
     to_color_strings)
 
@@ -91,7 +92,7 @@ def full_brain_info(volume_img, mesh='fsaverage5', threshold=None,
 
     """
     info = {}
-    mesh = _check_mesh(mesh)
+    mesh = surface.surface._check_mesh(mesh)
     surface_maps = {
         h: surface.vol_to_surf(volume_img, mesh['pial_{}'.format(h)],
                                **vol_to_surf_kwargs)