Merge branch 'master' into plot_fix

This updates my branch with recent changes to nilearn.

doc/conf.py

@@ -37,6 +37,7 @@
 # absolute, like shown here.
 sys.path.insert(0, os.path.abspath('sphinxext'))
 import sphinx_gallery
+from github_link import make_linkcode_resolve
 
 # We also add the directory just above to enable local imports of nilearn
 sys.path.insert(0, os.path.abspath('..'))
@@ -53,6 +54,7 @@
               'sphinx.ext.intersphinx',
               'sphinxcontrib.bibtex',
               'numpydoc',
+              'sphinx.ext.linkcode',
               ]
 
 autosummary_generate = True
@@ -97,7 +99,7 @@
 
 # General information about the project.
 project = u'Nilearn'
-copyright = u'The nilearn developers 2010-2020'
+copyright = u'The nilearn developers 2010-2021'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -354,3 +356,12 @@ def touch_example_backreferences(app, what, name, obj, options, lines):
 def setup(app):
     app.add_javascript('copybutton.js')
     app.connect('autodoc-process-docstring', touch_example_backreferences)
+
+
+
+# The following is used by sphinx.ext.linkcode to provide links to github
+linkcode_resolve = make_linkcode_resolve('nilearn',
+                                         'https://github.com/nilearn/'
+                                         'nilearn/blob/{revision}/'
+                                         '{package}/{path}#L{lineno}') 
+

doc/glm/second_level_model.rst

@@ -31,8 +31,8 @@ fits the model is :func:`nilearn.glm.second_level.SecondLevelModel.fit`.
 
 Some examples to get you going with second level models are provided below::
   * General design matrix setup: :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_design_matrix.py`
-  * One-sample testing, unpaired: :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_one_sample_test.py`
-  * One-sample testing, paired: :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_paired_sample_test.py`
+  * One-sample testing: :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_one_sample_test.py`
+  * Two-sample testing, unpaired and paired: :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_two_sample_test.py`
   * Complex contrast: :ref:`sphx_glr_auto_examples_05_glm_second_level_plot_second_level_association_test.py`
 
 

doc/sphinxext/github_link.py

@@ -0,0 +1,89 @@
+from operator import attrgetter
+import inspect
+import subprocess
+import os
+import sys
+from functools import partial
+
+REVISION_CMD = 'git rev-parse --short HEAD'
+
+
+def _get_git_revision():
+    try:
+        revision = subprocess.check_output(REVISION_CMD.split()).strip()
+    except (subprocess.CalledProcessError, OSError):
+        print('Failed to execute git to get revision')
+        return None
+    return revision.decode('utf-8')
+
+
+def _linkcode_resolve(domain, info, package, url_fmt, revision):
+    """Determine a link to online source for a class/method/function
+
+    This is called by sphinx.ext.linkcode
+
+    An example with a long-untouched module that everyone has
+    >>> _linkcode_resolve('py', {'module': 'tty',
+    ...                          'fullname': 'setraw'},
+    ...                   package='tty',
+    ...                   url_fmt='http://hg.python.org/cpython/file/'
+    ...                           '{revision}/Lib/{package}/{path}#L{lineno}',
+    ...                   revision='xxxx')
+    'http://hg.python.org/cpython/file/xxxx/Lib/tty/tty.py#L18'
+    """
+
+    if revision is None:
+        return
+    if domain not in ('py', 'pyx'):
+        return
+    if not info.get('module') or not info.get('fullname'):
+        return
+
+    class_name = info['fullname'].split('.')[0]
+    module = __import__(info['module'], fromlist=[class_name])
+    obj = attrgetter(info['fullname'])(module)
+
+    # Unwrap the object to get the correct source
+    # file in case that is wrapped by a decorator
+    obj = inspect.unwrap(obj)
+
+    try:
+        fn = inspect.getsourcefile(obj)
+    except Exception:
+        fn = None
+    if not fn:
+        try:
+            fn = inspect.getsourcefile(sys.modules[obj.__module__])
+        except Exception:
+            fn = None
+    if not fn:
+        return
+
+    # Don't include filenames from outside this package's tree
+    if os.path.dirname(__import__(package).__file__) not in fn:
+        return
+
+    fn = os.path.relpath(fn,
+                         start=os.path.dirname(__import__(package).__file__))
+    try:
+        lineno = inspect.getsourcelines(obj)[1]
+    except Exception:
+        lineno = ''
+    return url_fmt.format(revision=revision, package=package,
+                          path=fn, lineno=lineno)
+
+
+def make_linkcode_resolve(package, url_fmt):
+    """Returns a linkcode_resolve function for the given URL format
+
+    revision is a git commit reference (hash or name)
+
+    package is the name of the root module of the package
+
+    url_fmt is along the lines of ('https://github.com/USER/PROJECT/'
+                                   'blob/{revision}/{package}/'
+                                   '{path}#L{lineno}')
+    """
+    revision = _get_git_revision()
+    return partial(_linkcode_resolve, revision=revision, package=package,
+                   url_fmt=url_fmt)

doc/whats_new.rst

@@ -12,14 +12,23 @@ Fixes
   in the same order as for the signals, i.e., first detrending and
   then temporal filtering (https://github.com/nilearn/nilearn/issues/2730).
 - Fix number of attributes returned by the
-  :func:`nilearn.glm.first_level.FirstLevelModel._get_voxelwise_model_attribute` method in the first level model.
+  `nilearn.glm.first_level.FirstLevelModel._get_voxelwise_model_attribute` method in the first level model.
   It used to return only the first attribute, and now returns as many attributes as design matrices.
-
+- Plotting functions that show a stack of slices from a 3D image (e.g. 
+  :func:`nilearn.plotting.plot_stat_map`) will now plot the slices in the user 
+  specified order, rather than automatically sorting into ascending order
+  (https://github.com/nilearn/nilearn/issues/1155). 
 
 Enhancements
 ------------
 
-- :func:`nilearn.plotting.view_markers` now accept an optional argument `marker_labels` to provide labels to each marker.
+- :func:`nilearn.plotting.view_markers` now accepts an optional argument `marker_labels` to provide labels to each marker.
+- :func:`nilearn.plotting.plot_surf` now accepts new values for `avg_method` argument, such as `min`, `max`, or even a custom python function to compute the value displayed for each face of the plotted mesh.
+- :func:`nilearn.plotting.view_img_on_surf` can now optionally pass through
+  parameters to :func:`nilearn.surface.vol_to_surf` using the
+  `vol_to_surf_kwargs` argument. One application is better HTML visualization of
+  atlases.
+  (https://nilearn.github.io/auto_examples/01_plotting/plot_3d_map_to_surface_projection.html)
 
 .. _v0.7.1:
 

examples/01_plotting/plot_3d_map_to_surface_projection.py

@@ -148,3 +148,25 @@
 # view.open_in_browser()
 
 view
+
+##############################################################################
+# Impact of plot parameters on visualization
+# ------------------------------------------
+# You can specify arguments to be passed on to the function
+# :func:`nilearn.surface.vol_to_surf` using `vol_to_surf_kwargs`. This allows
+# fine-grained control of how the input 3D image is resampled and interpolated -
+# for example if you are viewing a volumetric atlas, you would want to avoid
+# averaging the labels between neighboring regions. Using nearest-neighbor
+# interpolation with zero radius will achieve this.
+
+destrieux = datasets.fetch_atlas_destrieux_2009()
+
+view = plotting.view_img_on_surf(
+    destrieux.maps,
+    surf_mesh="fsaverage",
+    vol_to_surf_kwargs={"n_samples": 1, "radius": 0.0, "interpolation": "nearest"},
+    symmetric_cmap=False,
+)
+
+# view.open_in_browser()
+view

examples/04_glm_first_level/write_events_file.py

@@ -63,3 +63,10 @@
 tsvfile = 'localizer_events.tsv'
 events.to_csv(tsvfile, sep='\t', index=False)
 print("Created the events file in %s " % tsvfile)
+
+#########################################################################
+# Optionally, the events can be visualized using the plot_event function.
+from matplotlib import pyplot as plt
+from nilearn.plotting import plot_event
+plot_event(events, figsize=(15, 5))
+plt.show()