nilearn · NicolasGensollen · Jan 28, 2022 · May 7, 2021 · Dec 16, 2021 · Dec 16, 2021
diff --git a/doc/changes/latest.rst b/doc/changes/latest.rst
@@ -200,3 +200,9 @@ Changes
 - Descriptions of datasets retrieved with fetchers from :mod:`nilearn.datasets` are
   now python strings rather than `bytes`. Therefore, decoding the descriptions is no
   longer necessary.
+- Dataset fetchers returning a :class:`numpy.recarray` can now return a
+  :class:`pandas.DataFrame` instead. These fetchers now have a ``legacy_format`` optional
+  argument defaulting to ``True`` for backward compatibility. Users will be warned that
+  this parameter will default to ``False`` in release 0.11.0, making
+  :class:`pandas.DataFrame` the default return type instead or :class:`numpy.recarray`.
+  (See PR `#2829 <https://github.com/nilearn/nilearn/pull/2829>`_).
diff --git a/examples/01_plotting/plot_3d_map_to_surface_projection.py b/examples/01_plotting/plot_3d_map_to_surface_projection.py
@@ -209,7 +209,7 @@
 # averaging the labels between neighboring regions. Using nearest-neighbor
 # interpolation with zero radius will achieve this.
 
-destrieux = datasets.fetch_atlas_destrieux_2009()
+destrieux = datasets.fetch_atlas_destrieux_2009(legacy_format=False)
 
 view = plotting.view_img_on_surf(
     destrieux.maps,

diff --git a/examples/01_plotting/plot_dim_plotting.py b/examples/01_plotting/plot_dim_plotting.py
@@ -19,11 +19,12 @@
 
 from nilearn import datasets
 
-localizer_dataset = datasets.fetch_localizer_button_task()
+localizer_dataset = datasets.fetch_localizer_button_task(legacy_format=False)
 # Contrast map of motor task
 localizer_tmap_filename = localizer_dataset.tmap
 # Subject specific anatomical image
 localizer_anat_filename = localizer_dataset.anat
+
 ###########################################################################
 # Plotting with enhancement of background image with dim=-.5
 # --------------------------------------------------------------------------

diff --git a/examples/01_plotting/plot_prob_atlas.py b/examples/01_plotting/plot_prob_atlas.py
@@ -46,8 +46,9 @@
 # Dictionaries of Functional Modes (“DiFuMo”) atlas
 dim = 64
 res = 2
-difumo = datasets.fetch_atlas_difumo(dimension=dim,
-                                     resolution_mm=res)
+difumo = datasets.fetch_atlas_difumo(
+    dimension=dim, resolution_mm=res, legacy_format=False
+)
 
 # Visualization
 from nilearn import plotting

diff --git a/examples/02_decoding/plot_oasis_vbm.py b/examples/02_decoding/plot_oasis_vbm.py
@@ -56,9 +56,11 @@
 ############################################################################
 # Load Oasis dataset
 # -------------------
-oasis_dataset = datasets.fetch_oasis_vbm(n_subjects=n_subjects)
+oasis_dataset = datasets.fetch_oasis_vbm(
+    n_subjects=n_subjects, legacy_format=False
+)
 gray_matter_map_filenames = oasis_dataset.gray_matter_maps
-age = oasis_dataset.ext_vars['age'].astype(float)
+age = oasis_dataset.ext_vars['age'].values
 
 # Split data into training set and test set
 from sklearn.model_selection import train_test_split

diff --git a/examples/02_decoding/plot_oasis_vbm_space_net.py b/examples/02_decoding/plot_oasis_vbm_space_net.py
@@ -16,7 +16,9 @@
 import numpy as np
 from nilearn import datasets
 n_subjects = 200  # increase this number if you have more RAM on your box
-dataset_files = datasets.fetch_oasis_vbm(n_subjects=n_subjects)
+dataset_files = datasets.fetch_oasis_vbm(
+    n_subjects=n_subjects, legacy_format=False
+)
 age = dataset_files.ext_vars['age'].astype(float)
 age = np.array(age)
 gm_imgs = np.array(dataset_files.gray_matter_maps)

diff --git a/examples/03_connectivity/plot_atlas_comparison.py b/examples/03_connectivity/plot_atlas_comparison.py
@@ -118,8 +118,9 @@ def lag_correlation(time_series, lag):
 # -----------------------------------------------------------------
 
 dim = 64
-difumo = datasets.fetch_atlas_difumo(dimension=dim,
-                                     resolution_mm=2)
+difumo = datasets.fetch_atlas_difumo(
+    dimension=dim, resolution_mm=2, legacy_format=False
+)
 
 ##########################################################################
 # Iterate over fetched atlases to extract coordinates - probabilistic

diff --git a/examples/03_connectivity/plot_sphere_based_connectome.py b/examples/03_connectivity/plot_sphere_based_connectome.py
@@ -158,7 +158,7 @@
 #
 # First we fetch the coordinates of the Power atlas
 
-power = datasets.fetch_coords_power_2011()
+power = datasets.fetch_coords_power_2011(legacy_format=False)
 print('Power atlas comes with {0}.'.format(power.keys()))
 
 
@@ -306,7 +306,7 @@
 # -------------------------------------------
 #
 # We repeat the same steps for Dosenbach's atlas.
-dosenbach = datasets.fetch_coords_dosenbach_2010()
+dosenbach = datasets.fetch_coords_dosenbach_2010(legacy_format=False)
 
 coords = np.vstack((
     dosenbach.rois['x'],

diff --git a/examples/05_glm_second_level/plot_oasis.py b/examples/05_glm_second_level/plot_oasis.py
@@ -33,13 +33,15 @@
 # ------------------
 
 from nilearn import datasets
-oasis_dataset = datasets.fetch_oasis_vbm(n_subjects=n_subjects)
+oasis_dataset = datasets.fetch_oasis_vbm(
+    n_subjects=n_subjects, legacy_format=False
+)
 gray_matter_map_filenames = oasis_dataset.gray_matter_maps
 age = oasis_dataset.ext_vars['age'].astype(float)
 
 ###############################################################################
 # Sex is encoded as 'M' or 'F'. Hence, we make it a binary variable.
-sex = oasis_dataset.ext_vars['mf'] == b'F'
+sex = oasis_dataset.ext_vars['mf'] == 'F'
 
 ###############################################################################
 # Print basic information on the dataset.

diff --git a/examples/05_glm_second_level/plot_proportion_activated_voxels.py b/examples/05_glm_second_level/plot_proportion_activated_voxels.py
@@ -21,9 +21,10 @@
 # BOLD activity estimate divided by the uncertainty about this estimate.
 from nilearn.datasets import fetch_localizer_contrasts
 n_subjects = 16
-data = fetch_localizer_contrasts(["left vs right button press"], n_subjects,
-                                 get_tmaps=True)
-
+data = fetch_localizer_contrasts(
+    ["left vs right button press"], n_subjects,
+    get_tmaps=True, legacy_format=False
+)
 from nilearn import plotting
 
 ############################################################################

diff --git a/examples/05_glm_second_level/plot_second_level_association_test.py b/examples/05_glm_second_level/plot_second_level_association_test.py
@@ -19,7 +19,9 @@
 from nilearn import datasets
 n_samples = 94
 localizer_dataset = datasets.fetch_localizer_contrasts(
-    ['left button press (auditory cue)'], n_subjects=n_samples)
+    ['left button press (auditory cue)'],
+    n_subjects=n_samples, legacy_format=False
+)
 
 ##############################################################################
 # Let's print basic information on the dataset.
@@ -34,11 +36,13 @@
 ##############################################################################
 # It is worth to do a auality check and remove subjects with missing values.
 import numpy as np
-mask_quality_check = np.where(tested_var != b'n/a')[0]
+mask_quality_check = np.where(
+    np.logical_not(np.isnan(tested_var))
+)[0]
 n_samples = mask_quality_check.size
 contrast_map_filenames = [localizer_dataset.cmaps[i]
                           for i in mask_quality_check]
-tested_var = tested_var[mask_quality_check].astype(float).reshape((-1, 1))
+tested_var = tested_var[mask_quality_check].values.reshape((-1, 1))
 print("Actual number of subjects after quality check: %d" % n_samples)
 
 ############################################################################

diff --git a/examples/05_glm_second_level/plot_second_level_one_sample_test.py b/examples/05_glm_second_level/plot_second_level_one_sample_test.py
@@ -27,8 +27,10 @@
 # estimate.
 from nilearn.datasets import fetch_localizer_contrasts
 n_subjects = 16
-data = fetch_localizer_contrasts(["left vs right button press"], n_subjects,
-                                 get_tmaps=True)
+data = fetch_localizer_contrasts(
+    ["left vs right button press"], n_subjects,
+    get_tmaps=True, legacy_format=False
+)
 
 ###########################################################################
 # Display subject t_maps

diff --git a/examples/05_glm_second_level/plot_second_level_two_sample_test.py b/examples/05_glm_second_level/plot_second_level_two_sample_test.py
@@ -35,9 +35,13 @@
 # localizer dataset.
 n_subjects = 16
 sample_vertical = fetch_localizer_contrasts(
-    ["vertical checkerboard"], n_subjects, get_tmaps=True)
+    ["vertical checkerboard"], n_subjects,
+    get_tmaps=True, legacy_format=False
+)
 sample_horizontal = fetch_localizer_contrasts(
-    ["horizontal checkerboard"], n_subjects, get_tmaps=True)
+    ["horizontal checkerboard"], n_subjects,
+    get_tmaps=True, legacy_format=False
+)
 
 # Implicitly, there is a one-to-one correspondence between the two samples:
 # the first image of both samples comes from subject S1, the second from subject S2 etc.

diff --git a/examples/05_glm_second_level/plot_thresholding.py b/examples/05_glm_second_level/plot_thresholding.py
@@ -18,7 +18,8 @@
 from nilearn import datasets
 n_samples = 20
 localizer_dataset = datasets.fetch_localizer_calculation_task(
-    n_subjects=n_samples)
+    n_subjects=n_samples, legacy_format=False
+)
 
 #########################################################################
 # Get the set of individual statstical maps (contrast estimates)

diff --git a/examples/07_advanced/plot_localizer_mass_univariate_methods.py b/examples/07_advanced/plot_localizer_mass_univariate_methods.py
@@ -29,19 +29,23 @@
 # Load Localizer contrast
 n_samples = 94
 localizer_dataset = datasets.fetch_localizer_contrasts(
-    ['left button press (auditory cue)'], n_subjects=n_samples)
+    ['left button press (auditory cue)'],
+    n_subjects=n_samples, legacy_format=False
+)
 
 # print basic information on the dataset
 print('First contrast nifti image (3D) is located at: %s' %
       localizer_dataset.cmaps[0])
 
 tested_var = localizer_dataset.ext_vars['pseudo']
 # Quality check / Remove subjects with bad tested variate
-mask_quality_check = np.where(tested_var != b'n/a')[0]
+mask_quality_check = np.where(
+    np.logical_not(np.isnan(tested_var))
+)[0]
 n_samples = mask_quality_check.size
 contrast_map_filenames = [localizer_dataset.cmaps[i]
                           for i in mask_quality_check]
-tested_var = tested_var[mask_quality_check].astype(float).reshape((-1, 1))
+tested_var = tested_var[mask_quality_check].values.reshape((-1, 1))
 print("Actual number of subjects after quality check: %d" % n_samples)
 
 

diff --git a/examples/07_advanced/plot_localizer_simple_analysis.py b/examples/07_advanced/plot_localizer_simple_analysis.py
@@ -25,7 +25,8 @@
 # Load Localizer contrast
 n_samples = 20
 localizer_dataset = datasets.fetch_localizer_calculation_task(
-    n_subjects=n_samples)
+    n_subjects=n_samples, legacy_format=False
+)
 tested_var = np.ones((n_samples, 1))
 
 

diff --git a/nilearn/_utils/docs.py b/nilearn/_utils/docs.py
@@ -35,6 +35,13 @@
 ax : :class:`~matplotlib.axes.Axes`
     The matplotlib axes in which the plots will be drawn."""
 
+# Legacy_format
+docdict['legacy_format'] = """
+legacy_format : :obj:`bool`, optional
+    If set to ``True``, the fetcher will return recarrays. Otherwise,
+    it will return pandas dataframes.
+    Default=True."""
+
 # Resume
 docdict['resume'] = """
 resume : :obj:`bool`, optional

diff --git a/nilearn/datasets/__init__.py b/nilearn/datasets/__init__.py
@@ -2,7 +2,6 @@
 Helper functions to download NeuroImaging datasets
 """
 
-from warnings import warn
 from .struct import (fetch_icbm152_2009, load_mni152_template,
                      load_mni152_brain_mask, load_mni152_gm_template,
                      load_mni152_gm_mask, load_mni152_wm_template,
@@ -90,7 +89,3 @@
            'fetch_fiac_first_level',
            ]
 
-warn("Fetchers from the nilearn.datasets module will be "
-     "updated in version 0.9 to return python strings "
-     "instead of bytes and Pandas dataframes instead of "
-     "Numpy arrays.", FutureWarning)