EXAMPLE: simplofy the neurovault ICA example

doc/modules/reference.rst

@@ -85,6 +85,7 @@ uses.
    fetch_oasis_vbm
    fetch_megatrawls_netmats
    fetch_cobre
+   fetch_neurovault
    get_data_dirs
    load_mni152_template
    load_mni152_brain_mask

doc/whats_new.rst

@@ -171,10 +171,10 @@ Bug fixes
      the size of a voxel
    - :class:`nilearn.regions.RegionExtractor` handles data containing Nans.
    - Confound regression does not force systematically the normalization of
-     the confounds. 
+     the confounds.
    - Force time series normalization in
      :class:`nilearn.connectome.ConnectivityMeasure`
-     and check dimensionality of the input. 
+     and check dimensionality of the input.
    - `nilearn._utils.numpy_conversions.csv_to_array` could consider
      valid CSV files as invalid.
 

examples/05_advanced/plot_ica_neurovault.py

@@ -0,0 +1,145 @@
+"""
+NeuroVault cross-study ICA maps.
+================================
+
+This example shows how to download statistical maps from
+NeuroVault, label them with NeuroSynth terms,
+and compute ICA components across all the maps.
+
+See :func:`nilearn.datasets.fetch_neurovault`
+documentation for more details.
+
+"""
+# Author: Ben Cipollini
+# License: BSD
+# Ported from code authored by Chris Filo Gorgolewski, Gael Varoquaux
+# https://github.com/NeuroVault/neurovault_analysis
+import warnings
+
+import numpy as np
+from scipy import stats
+from sklearn.decomposition import FastICA
+
+from nilearn.datasets import fetch_neurovault
+from nilearn.image import new_img_like, load_img
+
+
+def math_img(img, dtype=np.float32):
+    """ Remove nan/inf entries."""
+    img = load_img(img)
+    img_data = img.get_data().astype(dtype)
+    img_data[~np.isfinite(img_data)] = 0
+    return new_img_like(img, img_data)
+
+
+######################################################################
+# Get image and term data
+
+# Download images
+# Here by default we only download 80 images to save time,
+# but for better results I recommend using at least 200.
+print("Fetching Neurovault images; "
+      "if you haven't downloaded any Neurovault data before "
+      "this will take several minutes.")
+nv_data = fetch_neurovault(max_images=80, fetch_neurosynth_words=True)
+
+images = nv_data['images']
+term_weights = nv_data['word_frequencies']
+vocabulary = nv_data['vocabulary']
+
+# Clean and report term scores
+term_weights[term_weights < 0] = 0
+total_scores = np.mean(term_weights, axis=0)
+
+print("\nTop 10 neurosynth terms from downloaded images:\n")
+print('{2:>20}{0:>15} : {1:<15}\n{2:>20}{2:->30}'.format(
+    'term', 'total score', ''))
+for term_idx in np.argsort(total_scores)[-10:][::-1]:
+    print('{0:>35} : {1:.3f}'.format(
+        vocabulary[term_idx], total_scores[term_idx]))
+
+
+######################################################################
+# Reshape and mask images
+
+from nilearn.datasets import load_mni152_brain_mask
+from nilearn.input_data import NiftiMasker
+
+print("\nReshaping and masking images.\n")
+
+with warnings.catch_warnings():
+    warnings.simplefilter('ignore', UserWarning)
+    warnings.simplefilter('ignore', DeprecationWarning)
+
+    mask_img = load_mni152_brain_mask()
+    masker = NiftiMasker(
+        mask_img=mask_img, memory='nilearn_cache', memory_level=1)
+    masker = masker.fit()
+
+    # Images may fail to be transformed, and are of different shapes,
+    # so we need to transform one-by-one and keep track of failures.
+    X = []
+    is_usable = np.ones((len(images),), dtype=bool)
+
+    for index, image_path in enumerate(images):
+        image = math_img(image_path)
+        try:
+            X.append(masker.transform(image))
+        except Exception as e:
+            meta = nv_data['images_meta'][index]
+            print("Failed to mask/reshape image: id: {0}; "
+                  "name: '{1}'; collection: {2}; error: {3}".format(
+                      meta.get('id'), meta.get('name'),
+                      meta.get('collection_id'), e))
+            is_usable[index] = False
+
+# Now reshape list into 2D matrix, and remove failed images from terms
+X = np.vstack(X)
+term_weights = term_weights[is_usable, :]
+
+
+######################################################################
+# Run ICA and map components to terms
+
+print("Running ICA; may take time...")
+# We use a very small number of components as we have downloaded only 80
+# images. For better results, increase the number of images downloaded
+# and the number of components
+n_components = 16
+fast_ica = FastICA(n_components=n_components, random_state=0)
+ica_maps = fast_ica.fit_transform(X.T).T
+
+term_weights_for_components = np.dot(fast_ica.components_, term_weights)
+print('Done, plotting results.')
+
+
+######################################################################
+# Generate figures
+
+from nilearn import plotting
+import matplotlib.pyplot as plt
+
+for index, (ic_map, ic_terms) in enumerate(zip(ica_maps,
+        term_weights_for_components)):
+    if -ic_map.min() > ic_map.max():
+        # Flip the map's sign for prettiness
+        ic_map = - ic_map
+        ic_terms = - ic_terms
+
+    ic_threshold = stats.scoreatpercentile(np.abs(ic_map), 90)
+    ic_img = masker.inverse_transform(ic_map)
+    important_terms = vocabulary[np.argsort(ic_terms)[-3:]]
+    title = 'IC%i  %s' % (index, ', '.join(important_terms[::-1]))
+
+    plotting.plot_stat_map(ic_img,
+        threshold=ic_threshold, colorbar=False,
+        title=title)
+
+
+######################################################################
+# As we can see, some of the components capture cognitive or neurological
+# maps, while other capture noise in the database. More data, better
+# filtering, and better cognitive labels would give better maps
+
+# Done.
+plt.show()

examples/05_advanced/plot_neurovault_meta_analysis.py

@@ -0,0 +1,92 @@
+"""
+NeuroVault meta-analysis of stop-go paradigm studies.
+=====================================================
+
+This example shows how to download statistical maps from
+NeuroVault
+
+See :func:`nilearn.datasets.fetch_neurovault`
+documentation for more details.
+
+"""
+import scipy
+
+from nilearn.datasets import neurovault as nv
+from nilearn.image import new_img_like, load_img, math_img
+
+
+######################################################################
+# Fetch images for "successful stop minus go"-like protocols.
+
+# Only 7 images match our critera; set max_images to 7
+# so that if we already have them we won't look for more.
+nv_data = nv.fetch_neurovault(
+    max_images=7,
+    cognitive_paradigm_cogatlas=nv.Contains('stop signal'),
+    contrast_definition=nv.Contains('succ', 'stop', 'go'),
+    map_type='T map')
+
+images_meta = nv_data['images_meta']
+collections = nv_data['collections_meta']
+
+######################################################################
+# Visualize the data
+
+from nilearn import plotting
+
+for im in images_meta:
+    plotting.plot_glass_brain(im['absolute_path'],
+                              title='image {0}: {1}'.format(im['id'],
+                                    im['contrast_definition']))
+
+######################################################################
+# Compute statistics
+
+
+def t_to_z(t_scores, deg_of_freedom):
+    p_values = scipy.stats.t.sf(t_scores, df=deg_of_freedom)
+    z_values = scipy.stats.norm.isf(p_values)
+    return z_values
+
+
+# Compute z values
+mean_maps = []
+z_imgs = []
+ids = set()
+print("\nComputing maps...")
+for collection in [col for col in collections
+                   if not(col['id'] in ids or ids.add(col['id']))]:
+    print("\n\nCollection {0}:".format(collection['id']))
+
+    # convert t to z
+    image_z_niis = []
+    for this_meta in images_meta:
+        if this_meta['collection_id'] != collection['id']:
+            # We don't want to load this image
+            continue
+        # Load and validate the downloaded image.
+        nii = load_img(this_meta['absolute_path'])
+        deg_of_freedom = this_meta['number_of_subjects'] - 2
+        print("     Image {1}: degrees of freedom: {2}".format(
+            "", this_meta['id'], deg_of_freedom))
+
+        # Convert data, create new image.
+        z_img = new_img_like(nii,
+                    t_to_z(nii.get_data(), deg_of_freedom=deg_of_freedom))
+
+        z_imgs.append(z_img)
+        image_z_niis.append(nii)
+
+
+######################################################################
+# Plot the combined z maps
+
+cut_coords = [-15, -8, 6, 30, 46, 62]
+nii = math_img('np.sum(z_imgs, axis=3) / np.sqrt(z_imgs.shape[3])',
+               z_imgs=z_imgs)
+
+plotting.plot_stat_map(nii, display_mode='z', threshold=6,
+                        cut_coords=cut_coords, vmax=12)
+
+
+plotting.show()

nilearn/datasets/__init__.py

@@ -20,6 +20,7 @@
                     fetch_atlas_basc_multiscale_2015,
                     fetch_coords_dosenbach_2010)
 from .utils import get_data_dirs
+from .neurovault import fetch_neurovault
 
 __all__ = ['MNI152_FILE_PATH', 'fetch_icbm152_2009', 'load_mni152_template',
            'fetch_oasis_vbm',
@@ -35,4 +36,4 @@
            'fetch_megatrawls_netmats', 'fetch_cobre',
            'fetch_atlas_basc_multiscale_2015', 'fetch_coords_dosenbach_2010',
            'load_mni152_brain_mask', 'fetch_icbm152_brain_gm_mask',
-           'get_data_dirs']
+           'get_data_dirs', 'fetch_neurovault']

nilearn/datasets/description/neurovault.rst

@@ -0,0 +1,42 @@
+Neurovault statistical maps
+
+
+Notes
+-----
+Neurovault is a public repository of unthresholded statistical
+maps, parcellations, and atlases of the human brain. You can read
+about it and browse the images it contains at www.neurovault.org.
+
+Additionally, it is possible to ask Neurosynth to anotate the maps
+we have downloaded.  Neurosynth is a platform for large-scale,
+automated synthesis of fMRI data. It can be used to perform decoding.
+You can find out more about Neurosynth at www.neurosynth.org.
+
+Content
+-------
+    :'images': Nifti images representing the statistical maps.
+    :'images_meta': Dictionaries containing metadata for each image.
+    :'collections_meta': Dictionaries containing metadata for collections.
+    :'vocabulary': A list of words retrieved from neurosynth.org
+    :'word_frequencies': For each image, the weights of the words
+                         from 'vocabulary'.
+
+
+References
+----------
+.. [1] Gorgolewski KJ, Varoquaux G, Rivera G, Schwartz Y, Ghosh SS,
+   Maumet C, Sochat VV, Nichols TE, Poldrack RA, Poline J-B, Yarkoni
+   T and Margulies DS (2015) NeuroVault.org: a web-based repository
+   for collecting and sharing unthresholded statistical maps of the
+   human brain. Front. Neuroinform. 9:8.  doi:
+   10.3389/fninf.2015.00008
+
+.. [2] Yarkoni, Tal, Russell A. Poldrack, Thomas E. Nichols, David
+   C. Van Essen, and Tor D. Wager. "Large-scale automated synthesis
+   of human functional neuroimaging data." Nature methods 8, no. 8
+   (2011): 665-670.
+
+
+License
+-------
+All data are distributed under the CC0 license.