Merge pull request nilearn#1668 from jeromedockes/add_fsaverage

[MRG+1] add fsaverage fetcher

doc/modules/reference.rst

@@ -88,7 +88,7 @@ uses.
    fetch_miyawaki2008
    fetch_nyu_rest
    fetch_surf_nki_enhanced
-   fetch_surf_fsaverage5
+   fetch_surf_fsaverage
    fetch_atlas_surf_destrieux
    fetch_atlas_talairach
    fetch_oasis_vbm

doc/whats_new.rst

@@ -1,3 +1,21 @@
+0.4.3
+=====
+
+Changes
+-------
+
+    - `nilearn.datasets.fetch_surf_fsaverage5` is deprecated and will be
+      removed in a future release. Use :func:`nilearn.datasets.fetch_surf_fsaverage`,
+      with the parameter mesh="fsaverage5" (the default) instead.
+
+
+Enhancements
+------------
+
+    - Add :func:`nilearn.datasets.fetch_surf_fsaverage` to download either
+      fsaverage or fsaverage 5 (Freesurfer cortical meshes).
+
+
 0.4.2
 =====
 Few important bugs fix release for OHBM conference.
@@ -358,7 +376,7 @@ Enhancements
     - A function :func:`nilearn.plotting.plot_surf_roi` can be used for
       plotting statistical maps rois onto brain surface.
 
-    - A function :func:`nilearn.datasets.fetch_surf_fsaverage5` can be used
+    - A function `nilearn.datasets.fetch_surf_fsaverage5` can be used
       for surface data object to be as background map for the above plotting
       functions.
 

examples/01_plotting/plot_3d_map_to_surface_projection.py

@@ -23,7 +23,7 @@
 # Get a cortical mesh
 # -------------------
 
-fsaverage = datasets.fetch_surf_fsaverage5()
+fsaverage = datasets.fetch_surf_fsaverage()
 
 ##############################################################################
 # Sample the 3D data around each node of the mesh
@@ -53,4 +53,22 @@
 plotting.plot_stat_map(localizer_tmap, display_mode='x', threshold=1.,
                        cut_coords=range(0, 51, 10), title='Slices')
 
+
+##############################################################################
+# Plot with higher-resolution mesh
+# --------------------------------
+#
+# `fetch_surf_fsaverage` takes a "mesh" argument which specifies
+# wether to fetch the low-resolution fsaverage5 mesh, or the high-resolution
+# fsaverage mesh. using mesh="fsaverage" will result in more memory usage and
+# computation time, but finer visualizations.
+
+big_fsaverage = datasets.fetch_surf_fsaverage('fsaverage')
+texture = surface.vol_to_surf(localizer_tmap, big_fsaverage.pial_right)
+
+plotting.plot_surf_stat_map(big_fsaverage.infl_right, texture, hemi='right',
+                            title='Surface right hemisphere: fine mesh',
+                            threshold=1., bg_map=big_fsaverage.sulc_right)
+
+
 plotting.show()

examples/01_plotting/plot_surf_atlas.py

@@ -35,7 +35,7 @@
 # Retrieve fsaverage5 surface dataset for the plotting background. It contains
 # the surface template as pial and inflated version and a sulcal depth maps
 # which is used for shading
-fsaverage = datasets.fetch_surf_fsaverage5()
+fsaverage = datasets.fetch_surf_fsaverage()
 
 # The fsaverage dataset contains file names pointing to the file locations
 print('Fsaverage5 pial surface of left hemisphere is at: %s' %

examples/01_plotting/plot_surf_stat_map.py

@@ -69,7 +69,7 @@
 labels = destrieux_atlas['labels']
 
 # Fsaverage5 surface template
-fsaverage = datasets.fetch_surf_fsaverage5()
+fsaverage = datasets.fetch_surf_fsaverage()
 
 # The fsaverage dataset contains file names pointing to
 # the file locations

nilearn/datasets/__init__.py

@@ -5,7 +5,8 @@
 from .struct import (fetch_icbm152_2009, load_mni152_template,
                      load_mni152_brain_mask, fetch_oasis_vbm,
                      fetch_icbm152_brain_gm_mask,
-                     MNI152_FILE_PATH, fetch_surf_fsaverage5)
+                     MNI152_FILE_PATH, fetch_surf_fsaverage5,
+                     fetch_surf_fsaverage)
 from .func import (fetch_haxby_simple, fetch_haxby, fetch_nyu_rest,
                    fetch_adhd, fetch_miyawaki2008,
                    fetch_localizer_contrasts, fetch_abide_pcp,
@@ -41,6 +42,7 @@
            'fetch_atlas_yeo_2011', 'fetch_mixed_gambles', 'fetch_atlas_aal',
            'fetch_megatrawls_netmats', 'fetch_cobre',
            'fetch_surf_nki_enhanced', 'fetch_surf_fsaverage5',
+           'fetch_surf_fsaverage',
            'fetch_atlas_basc_multiscale_2015', 'fetch_coords_dosenbach_2010',
            'fetch_neurovault', 'fetch_neurovault_ids',
            'load_mni152_brain_mask', 'fetch_icbm152_brain_gm_mask',

nilearn/datasets/description/fsaverage.rst

@@ -0,0 +1,21 @@
+fsaverage
+
+
+Notes
+-----
+Fsaverage standard surface as distributed with Freesurfer (Fischl et al, 1999)
+
+Content
+-------
+    :'pial_left': Gifti file, left hemisphere pial surface mesh
+    :'pial_right': Gifti file, right hemisphere pial surface mesh
+    :'infl_left': Gifti file, left hemisphere inflated pial surface mesh
+    :'infl_right': Gifti file, right hemisphere inflated pial
+                   surface mesh
+    :'sulc_left': Gifti file, left hemisphere sulcal depth data
+    :'sulc_right': Gifti file, right hemisphere sulcal depth data
+
+References
+----------
+Fischl et al, (1999). High-resolution intersubject averaging and a
+coordinate system for the cortical surface. Hum Brain Mapp 8, 272-284.

nilearn/datasets/struct.py

@@ -7,9 +7,11 @@
 from scipy import ndimage
 from sklearn.datasets.base import Bunch
 
-from .utils import _get_dataset_dir, _fetch_files, _get_dataset_descr
+from .utils import (_get_dataset_dir, _fetch_files,
+                    _get_dataset_descr, _uncompress_file)
 
 from .._utils import check_niimg, niimg
+from .._utils.exceptions import VisibleDeprecationWarning
 from ..image import new_img_like
 
 _package_directory = os.path.dirname(os.path.abspath(__file__))
@@ -423,25 +425,77 @@ def fetch_oasis_vbm(n_subjects=None, dartel_version=True, data_dir=None,
         description=fdescr)
 
 
-def fetch_surf_fsaverage5(data_dir=None, url=None, resume=True, verbose=1):
-
-    """ Download Freesurfer fsaverage5 surface
+def fetch_surf_fsaverage(mesh='fsaverage5', data_dir=None):
+    """ Download a Freesurfer fsaverage surface
 
     Parameters
     ----------
-    data_dir: str, optional
+    mesh: str, optional (default='fsaverage5')
+        Which mesh to fetch.
+        'fsaverage5': the low-resolution fsaverage5 mesh (10242 nodes)
+        'fsaverage': the high-resolution fsaverage mesh (163842 nodes)
+        (high-resolution fsaverage will result in
+        more computation time and memory usage)
+
+    data_dir: str, optional (default=None)
         Path of the data directory. Used to force data storage in a specified
-        location. Default: None
+        location.
 
-    url: str, optional
-        Override download URL. Used for test only (or if you setup a mirror of
-        the data). Default: None
+    Returns
+    -------
+    data: sklearn.datasets.base.Bunch
+        Dictionary-like object, the interest attributes are :
+         - 'pial_left': Gifti file, left hemisphere pial surface mesh
+         - 'pial_right': Gifti file, right hemisphere pial surface mesh
+         - 'infl_left': Gifti file, left hemisphere inflated pial surface mesh
+         - 'infl_right': Gifti file, right hemisphere inflated pial
+                         surface mesh
+         - 'sulc_left': Gifti file, left hemisphere sulcal depth data
+         - 'sulc_right': Gifti file, right hemisphere sulcal depth data
 
-    resume: bool, optional (default True)
-        If True, try resuming download if possible.
+    References
+    ----------
+    Fischl et al, (1999). High-resolution intersubject averaging and a
+    coordinate system for the cortical surface. Hum Brain Mapp 8, 272-284.
+
+    """
+    meshes = {'fsaverage5': _fetch_surf_fsaverage5,
+              'fsaverage': _fetch_surf_fsaverage}
+    if mesh not in meshes:
+        raise ValueError(
+            "'mesh' should be one of {}; {!r} was provided".format(
+                list(meshes.keys()), mesh))
+    return meshes[mesh](data_dir=data_dir)
+
+
+def _fetch_surf_fsaverage(data_dir=None):
+    dataset_dir = _get_dataset_dir('fsaverage', data_dir=data_dir)
+    url = 'https://www.nitrc.org/frs/download.php/10846/fsaverage.tar.gz'
+    if not os.path.isdir(os.path.join(dataset_dir, 'fsaverage')):
+        _fetch_files(dataset_dir, [('fsaverage.tar.gz', url, {})])
+        _uncompress_file(os.path.join(dataset_dir, 'fsaverage.tar.gz'))
+    result = {
+        name: os.path.join(dataset_dir, 'fsaverage', '{}.gii'.format(name))
+        for name in ['pial_right', 'sulc_right', 'sulc_left', 'pial_left']}
+    result['infl_left'] = os.path.join(
+        dataset_dir, 'fsaverage', 'inflated_left.gii')
+    result['infl_right'] = os.path.join(
+        dataset_dir, 'fsaverage', 'inflated_right.gii')
+
+    result['description'] = str(_get_dataset_descr('fsaverage'))
+    return Bunch(**result)
+
+
+def fetch_surf_fsaverage5(data_dir=None, url=None, resume=True, verbose=1):
+    """ Deprecated since version 0.4.3
+
+    Use fetch_surf_fsaverage instead.
 
-    verbose: int, optional (default 1)
-        Defines the level of verbosity of the output.
+    Parameters
+    ----------
+    data_dir: str, optional (default=None)
+        Path of the data directory. Used to force data storage in a specified
+        location.
 
     Returns
     -------
@@ -459,7 +513,16 @@ def fetch_surf_fsaverage5(data_dir=None, url=None, resume=True, verbose=1):
     ----------
     Fischl et al, (1999). High-resolution intersubject averaging and a
     coordinate system for the cortical surface. Hum Brain Mapp 8, 272-284.
+
     """
+    warnings.warn("fetch_surf_fsaverage5 has been deprecated and will "
+                  "be removed in a future release. "
+                  "Use fetch_surf_fsaverage(mesh='fsaverage5')",
+                  VisibleDeprecationWarning, stacklevel=2)
+    return fetch_surf_fsaverage(mesh='fsaverage5', data_dir=data_dir)
+
+
+def _fetch_surf_fsaverage5(data_dir=None, url=None, resume=True, verbose=1):
     if url is None:
         url = 'https://www.nitrc.org/frs/download.php/'
 

nilearn/datasets/tests/test_struct.py

@@ -164,18 +164,14 @@ def test_fetch_icbm152_brain_gm_mask():
 @with_setup(setup_mock, teardown_mock)
 @with_setup(tst.setup_tmpdata, tst.teardown_tmpdata)
 def test_fetch_surf_fsaverage():
+    # for mesh in ['fsaverage5', 'fsaverage']:
+    for mesh in ['fsaverage']:
 
-    dataset = struct.fetch_surf_fsaverage5(data_dir=tst.tmpdir, verbose=0)
+        dataset = struct.fetch_surf_fsaverage(
+            mesh, data_dir=tst.tmpdir)
 
-    keys = ['pial_left', 'pial_right', 'infl_left', 'infl_right',
-            'sulc_left', 'sulc_right']
+        keys = {'pial_left', 'pial_right', 'infl_left', 'infl_right',
+                'sulc_left', 'sulc_right'}
 
-    filenames = ['pial.left.gii', 'pial.right.gii', 'pial_inflated.left.gii',
-                 'pial_inflated.right.gii', 'sulc.left.gii', 'sulc.right.gii']
-
-    for key, filename in zip(keys, filenames):
-        assert_equal(dataset[key], os.path.join(tst.tmpdir, 'fsaverage5',
-                                                filename))
-
-    assert_not_equal(dataset.description, '')
-    assert_equal(len(tst.mock_url_request.urls), len(keys))
+        assert keys.issubset(set(dataset.keys()))
+        assert_not_equal(dataset.description, '')

nilearn/plotting/surf_plotting.py

@@ -102,7 +102,7 @@ def plot_surf(surf_mesh, surf_map=None, bg_map=None,
 
     See Also
     --------
-    nilearn.datasets.fetch_surf_fsaverage5 : For surface data object to be
+    nilearn.datasets.fetch_surf_fsaverage : For surface data object to be
         used as background map for this plotting function.
 
     nilearn.plotting.plot_surf_roi : For plotting statistical maps on brain
@@ -355,7 +355,7 @@ def plot_surf_stat_map(surf_mesh, stat_map, bg_map=None,
 
     See Also
     --------
-    nilearn.datasets.fetch_surf_fsaverage5 : For surface data object to be
+    nilearn.datasets.fetch_surf_fsaverage : For surface data object to be
         used as background map for this plotting function.
 
     nilearn.plotting.plot_surf : For brain surface visualization.
@@ -451,7 +451,7 @@ def plot_surf_roi(surf_mesh, roi_map, bg_map=None,
 
     See Also
     --------
-    nilearn.datasets.fetch_surf_fsaverage5: For surface data object to be
+    nilearn.datasets.fetch_surf_fsaverage: For surface data object to be
         used as background map for this plotting function.
 
     nilearn.plotting.plot_surf: For brain surface visualization.