Repository: nilearn/nilearn

Issue:
rename fetch_atlas_power_2011 to fetch_coords_power_2011
since this function gives only the coordinates



Discussion:
In all papers I've read, this is referred as "Power atlas". So I'm -1 on this one. If we start doing this, that means that all "atlas" functions should be renames to either "labels" or "maps" depending on their type.

Hum :$

It's going to make teaching even harder. When I teach I warn users that
they are 2 types of atlases, and I spend time explaining the differences.
How I need to talk about three... I am not very convinced.

for me the difference is bigger between giving coordinates vs regions than between maps vs labels

Tricky case...introduce something like "coordinate collections"?

On the top of it, "fetch" might not make sense because sets of coordinates are not space/memory-demanding

> On the top of it, "fetch" might not make sense because sets of coordinates are
> not space/memory-demanding

Indeed: we are not "fetching" them: they are provided in a CSV file in
the repo.

That's an oversight, the function should be named "load_...".

> Indeed: we are not "fetching" them: they are provided in a CSV file in
> the repo.
> 
> That's an oversight, the function should be named "load_...".

My 2c: I'd rather have a consistent naming with fetch_ rather than something that is based on implementation details (whether the data is part of the repo or not).

> My 2c: I'd rather have a consistent naming with fetch_ rather than something
> that is based on implementation details (whether the data is part of the repo
> or not).

It's not an implementation detail: it's about whether it will download
something or not. Therefore is conditions disk space and the need for
internet access.

> It's not an implementation detail: it's about whether it will download something or not. Therefore is conditions disk space and the need for internet access.

Not entirely convinced the user cares that much about these details, he just wants to get the data and  vast majority of cases has the resources (internet + disk space) to do so.

Also I could imagine doing `from nilearn.datasets import fetch_atlas<TAB>` and being confused because  fetch_atlas_power_2011 is not listed after the tab completion.

> Also I could imagine doing `from nilearn.datasets import fetch_atlas<TAB>` and being confused because  fetch_atlas_power_2011 is not listed after the tab completion.

Same problem with the `fetch_coords` renaming.

> Same problem with the fetch_coords renaming.

I was more arguing about fetch_ vs load_ here.

> I was more arguing about fetch_ vs load_ here.

The modern neuroscience hacker working at airports, in train and metro will probably care whether the fast prototyping he or she is effectuating in an IPython notebook will require an internet connection or not....

> The modern neuroscience hacker working at airports, in train and metro will probably care whether the fast prototyping he or she is effectuating in an IPython notebook will require an internet connection or not....

The modern neuroscience hacker will very likely have the data already downloaded because he uses nilearn extensively :-). Since my previous comment, I realised scikit-learn has this load_ vs fetch_ convention, so that's probably fine if people are used to it.

> The modern neuroscience hacker will very likely have the data already
> downloaded because he uses nilearn extensively :-).

No

> > The modern neuroscience hacker will very likely have the data already
> >  downloaded because he uses nilearn extensively :-).
> 
> No

For the record that was meant as a tongue in cheek comment. IIRC most datasets in nilearn need to be downloaded the first time. The poor modern neuroscience hacker without an internet connection is slightly out of luck I am afraid, unless of course he has downloaded the dataset already.

Other than that I reckon we are getting a bit side-tracked with respect to the original issue.

> ```
>     The modern neuroscience hacker will very likely have the data already
>     downloaded because he uses nilearn extensively :-).
> 
> No
> ```
> 
> For the record that was meant as a tongue in cheek comment.

Sorry, I forgot the smiley, in my comment.

I'm setting it to milestone 0.2.3 because I think that it is important to make a decision on this subject now.

Regarding atlas vs. coords: I prefer to keep atlas since I've never read Power coordinates anywhere. But I have no strong feelings, I am OK for changing it to coords if majority votes for it.

Regarding fetch vs load: I am not against the distinction between online/offline but what bothers me is that this comes before the fact that the dataset is an atlas. First, I think that the difference between `fetch` and `load` is not clear for everybody (let's ask Baptiste if he knows the difference...). A better option would be to put in the name but further. Something like `fetch_atlas_blabla_offline`. We can even make it closer like `fetch_atlas_offline_blabla` but putting it in first position will lose people that are used to do `fetch_atlas_<TAB>` like Loic said.

I don't have strong feelings, but `fetch_coords_power_2011` makes it clear that the output is not a standard atlas, so I'd rather go for it. I'm afraid that otherwise people will complain they don't know how to handle it.


Resolving patch:
diff --git a/nilearn/datasets/__init__.py b/nilearn/datasets/__init__.py
--- a/nilearn/datasets/__init__.py
+++ b/nilearn/datasets/__init__.py
@@ -10,10 +10,11 @@
                    fetch_megatrawls_netmats, fetch_cobre)
 from .atlas import (fetch_atlas_craddock_2012, fetch_atlas_destrieux_2009,
                     fetch_atlas_harvard_oxford, fetch_atlas_msdl,
-                    fetch_atlas_power_2011, fetch_atlas_smith_2009,
+                    fetch_atlas_power_2011, fetch_coords_power_2011,
+                    fetch_atlas_smith_2009,
                     fetch_atlas_yeo_2011, fetch_atlas_aal,
                     fetch_atlas_basc_multiscale_2015,
-                    fetch_atlas_dosenbach_2010)
+                    fetch_coords_dosenbach_2010)
 
 __all__ = ['fetch_icbm152_2009', 'load_mni152_template', 'fetch_oasis_vbm',
            'fetch_haxby_simple', 'fetch_haxby', 'fetch_nyu_rest',
@@ -21,7 +22,8 @@
            'fetch_abide_pcp', 'fetch_localizer_calculation_task',
            'fetch_atlas_craddock_2012', 'fetch_atlas_destrieux_2009',
            'fetch_atlas_harvard_oxford', 'fetch_atlas_msdl',
-           'fetch_atlas_power_2011', 'fetch_atlas_smith_2009',
+           'fetch_atlas_power_2011', 'fetch_coords_power_2011',
+           'fetch_atlas_smith_2009',
            'fetch_atlas_yeo_2011', 'fetch_mixed_gambles', 'fetch_atlas_aal',
            'fetch_megatrawls_netmats', 'fetch_cobre',
-           'fetch_atlas_basc_multiscale_2015', 'fetch_atlas_dosenbach_2010']
+           'fetch_atlas_basc_multiscale_2015', 'fetch_coords_dosenbach_2010']
diff --git a/nilearn/datasets/atlas.py b/nilearn/datasets/atlas.py
--- a/nilearn/datasets/atlas.py
+++ b/nilearn/datasets/atlas.py
@@ -4,9 +4,9 @@
 import os
 import xml.etree.ElementTree
 import numpy as np
-from scipy import ndimage
 
 from sklearn.datasets.base import Bunch
+from sklearn.utils import deprecated
 
 #from . import utils
 from .utils import _get_dataset_dir, _fetch_files, _get_dataset_descr
@@ -332,7 +332,13 @@ def fetch_atlas_msdl(data_dir=None, url=None, resume=True, verbose=1):
     return Bunch(labels=files[0], maps=files[1], description=fdescr)
 
 
+@deprecated('This function has been replace by fetch_coords_power_2011 and '
+            'will be removed in nilearn 0.2.5')
 def fetch_atlas_power_2011():
+    return fetch_coords_power_2011()
+
+
+def fetch_coords_power_2011():
     """Download and load the Power et al. brain atlas composed of 264 ROIs.
 
     Returns
@@ -366,9 +372,9 @@ def fetch_atlas_smith_2009(data_dir=None, mirror='origin', url=None,
         Path of the data directory. Used to force data storage in a non-
         standard location. Default: None (meaning: default)
     mirror: string, optional
-        By default, the dataset is downloaded from the original website of the atlas.
-        Specifying "nitrc" will force download from a mirror, with potentially
-        higher bandwith.
+        By default, the dataset is downloaded from the original website of the
+        atlas. Specifying "nitrc" will force download from a mirror, with
+        potentially higher bandwith.
     url: string, optional
         Download URL of the dataset. Overwrite the default URL.
 
@@ -726,7 +732,7 @@ def fetch_atlas_basc_multiscale_2015(version='sym', data_dir=None,
     return Bunch(**params)
 
 
-def fetch_atlas_dosenbach_2010():
+def fetch_coords_dosenbach_2010():
     """Load the Dosenbach et al. 160 ROIs. These ROIs cover
     much of the cerebral cortex and cerebellum and are assigned to 6
     networks.


Test patch:
diff --git a/nilearn/datasets/tests/test_atlas.py b/nilearn/datasets/tests/test_atlas.py
--- a/nilearn/datasets/tests/test_atlas.py
+++ b/nilearn/datasets/tests/test_atlas.py
@@ -192,8 +192,8 @@ def test_fetch_atlas_smith_2009():
     assert_not_equal(bunch.description, '')
 
 
-def test_fetch_atlas_power_2011():
-    bunch = atlas.fetch_atlas_power_2011()
+def test_fetch_coords_power_2011():
+    bunch = atlas.fetch_coords_power_2011()
     assert_equal(len(bunch.rois), 264)
     assert_not_equal(bunch.description, '')
 
@@ -312,8 +312,8 @@ def test_fetch_atlas_basc_multiscale_2015():
     assert_not_equal(data_asym.description, '')
 
 
-def test_fetch_atlas_dosenbach_2010():
-    bunch = atlas.fetch_atlas_dosenbach_2010()
+def test_fetch_coords_dosenbach_2010():
+    bunch = atlas.fetch_coords_dosenbach_2010()
     assert_equal(len(bunch.rois), 160)
     assert_equal(len(bunch.labels), 160)
     assert_equal(len(np.unique(bunch.networks)), 6)