Merge pull request #2013 from illdopejake/nilearn-sprint-example-cons…

…olidation

Nilearn sprint example consolidation

doc/connectivity/resting_state_networks.rst

@@ -6,12 +6,11 @@ Extracting functional brain networks: ICA and related
 
 .. topic:: **Page summary**
 
-   This page demonstrates the use of multi-subject Independent Component
-   Analysis (ICA) of movie-watching fMRI data
-   to extract brain networks in
-   an data-driven way. Here we use the 'CanICA' approach, that implements
-   a multivariate random effects model across subjects. A newer technique,
-   based on dictionary learning, is then described.
+   This page demonstrates the use of multi-subject decompositions models
+   to extract brain-networks from fMRI data in a data-driven way.
+   Specifically, we will apply Independent Component Analysis (ICA), which 
+   implements a multivariate random effects model across subjects. We will
+   then compare ICA to a newer technique, based on dictionary learning.
 
 
 .. currentmodule:: nilearn.decomposition
@@ -25,76 +24,58 @@ Multi-subject ICA: CanICA
       fMRI datasets", `NeuroImage Vol 51 (2010)
       <http://www.sciencedirect.com/science/article/pii/S1053811910001618>`_, p. 288-299
 
-Data preparation: retrieving example data
------------------------------------------
+Objective
+----------
+ICA is a useful approach for finding independent sources from fMRI
+images. ICA and similar techniques can be therefore used to define 
+regions or networks that share similar BOLD signal across time. The 
+CanICA incorporates information both within-subjects and across subjects
+to arrive at consensus components.
 
-We will use down-sampled data from the `brain development dataset
-<https://osf.io/5hju4/files/>`_ has been
-preprocessed using `FMRIPrep and Nilearn <https://osf.io/wjtyq/>`_.
-We use nilearn
-functions to fetch data from Internet and get the filenames (:ref:`more
-on data loading <loading_data>`):
+.. topic:: **Nilearn data for examples**
 
+   Nilearn provides easy-to-analyze data to explore functional connectivity and resting: the
+   `brain development dataset <https://osf.io/5hju4/files/>`_, which
+   has been preprocessed using `FMRIPrep and Nilearn <https://osf.io/wjtyq/>`_
+   We use nilearn functions to fetch data from Internet and get the 
+   filenames (:ref:`more on data loading <loading_data>`).
 
-.. literalinclude:: ../../examples/03_connectivity/plot_canica_analysis.py
-    :start-after: # First we load the brain development fmri data
-    :end-before:  ###############################################
-
-Applying CanICA
----------------
 
+Fitting CanICA model with nilearn
+---------------------------------
 :class:`CanICA` is a ready-to-use object that can be applied to
 multi-subject Nifti data, for instance presented as filenames, and will
 perform a multi-subject ICA decomposition following the CanICA model.
 As with every object in nilearn, we give its parameters at construction,
-and then fit it on the data.
-
-.. literalinclude:: ../../examples/03_connectivity/plot_canica_analysis.py
-    :start-after: # Here we apply CanICA on the data
-    :end-before: ####################################################################
-
-The components estimated are found as the `components_img_` attribute
-of the object. A 4D Nifti image.
-
-.. note::
-    The `components_img_` attribute is implemented from version 0.4.1 which
-    is easy for visualization without any additional step to unmask to image.
-    For users who have older versions, components image can be done by
-    unmasking attribute `components_`. See :ref:`section Inverse transform:
-    unmasking data <unmasking_step>`.
-
-Visualizing the results
------------------------
+and then fit it on the data. For examples of this process, see
+here: :ref:`sphx_glr_auto_examples_03_connectivity_plot_compare_decomposition.py`
 
-We can visualize the components as in the previous examples. The first plot
-shows a map generated from all the components. Then we plot an axial cut for
-each component separately.
+Once an ICA object has been fit to an fMRI dataset, the individual 
+components can be accessed as a 4D Nifti object using the 
+``components_img_`` attribute.
 
-.. literalinclude:: ../../examples/03_connectivity/plot_canica_analysis.py
-    :start-after: # To visualize we plot the outline of all components on one figure
-    :end-before: ####################################################################
+Visualizing results
+--------------------
+We can visualize each component outlined over the brain:
 
-.. figure:: ../auto_examples/03_connectivity/images/sphx_glr_plot_canica_analysis_001.png
+.. figure:: ../auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_001.png
    :align: center
-   :target: ../auto_examples/03_connectivity/plot_canica_analysis.html
-
-Finally, we can plot the map for different ICA components separately:
+   :target: ../auto_examples/03_connectivity/plot_compare_decomposition.html
 
-.. literalinclude:: ../../examples/03_connectivity/plot_canica_analysis.py
-    :start-after: # Finally, we plot the map for each ICA component separately
+We can also plot the map for different components separately:
 
-.. |left_img| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_canica_analysis_003.png
+.. |left_img| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_002.png
    :width: 23%
 
-.. |right_img| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_canica_analysis_004.png
+.. |right_img| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_003.png
    :width: 23%
 
 .. centered:: |left_img| |right_img|
 
 .. seealso::
 
    The full code can be found as an example:
-   :ref:`sphx_glr_auto_examples_03_connectivity_plot_canica_analysis.py`
+   :ref:`sphx_glr_auto_examples_03_connectivity_plot_compare_decomposition.py`
 
 .. note::
 
@@ -103,9 +84,8 @@ Finally, we can plot the map for different ICA components separately:
    a fair representation, you should display all components and
    investigate which one resemble those displayed above.
 
-Beyond ICA : Dictionary learning
-================================
-
+An alternative to ICA: Dictionary learning
+===========================================
 Recent work has shown that dictionary learning based techniques outperform
 ICA in term of stability and constitutes a better first step in a statistical
 analysis pipeline.
@@ -115,53 +95,35 @@ good extracted maps.
 
 .. topic:: **References**
 
-   * Arthur Mensch et al. `Compressed online dictionary learning for fast resting-state fMRI decomposition <https://hal.archives-ouvertes.fr/hal-01271033/>`_,
-     ISBI 2016, Lecture Notes in Computer Science
-
-Applying DictLearning
----------------------
+    * Arthur Mensch et al. `Compressed online dictionary learning for fast resting-state fMRI decomposition <https://hal.archives-ouvertes.fr/hal-01271033/>`_,
+      ISBI 2016, Lecture Notes in Computer Science
 
 :class:`DictLearning` is a ready-to-use class with the same interface as CanICA.
 Sparsity of output map is controlled by a parameter alpha: using a
 larger alpha yields sparser maps.
 
-.. literalinclude:: ../../examples/03_connectivity/plot_compare_decomposition.py
-    :start-after: # Dictionary learning
-    :end-before: ###############################################################################
+We can fit both estimators to compare them. 4D plotting offers an efficient way 
+to compare both resulting outputs.
 
-We can fit both estimators to compare them
-
-.. literalinclude:: ../../examples/03_connectivity/plot_compare_decomposition.py
-    :start-after: # Fit both estimators
-    :end-before: ###############################################################################
-
-Visualizing the results
------------------------
-
-4D plotting offers an efficient way to compare both resulting outputs
-
-.. literalinclude:: ../../examples/03_connectivity/plot_compare_decomposition.py
-    :start-after: # Visualize the results
-
-.. |left_img_decomp| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_001.png
+.. |left_img_decomp| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_022.png
    :target: ../auto_examples/03_connectivity/plot_compare_decomposition.html
    :width: 50%
-.. |right_img_decomp| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_003.png
+.. |right_img_decomp| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_023.png
    :target: ../auto_examples/03_connectivity/plot_compare_decomposition.html
    :width: 50%
 
-.. |left_img_decomp_single| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_002.png
+.. |left_img_decomp_single| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_024.png
    :target: ../auto_examples/03_connectivity/plot_compare_decomposition.html
    :width: 50%
-.. |right_img_decomp_single| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_004.png
+.. |right_img_decomp_single| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_025.png
    :target: ../auto_examples/03_connectivity/plot_compare_decomposition.html
    :width: 50%
 
 
 .. centered:: |left_img_decomp| |right_img_decomp|
 .. centered:: |left_img_decomp_single| |right_img_decomp_single|
 
-Maps obtained with dictionary leaning are often easier to exploit as they are
+Maps obtained with dictionary learning are often easier to exploit as they are
 less noisy than ICA maps, with blobs usually better defined. Typically,
 *smoothing can be lower than when doing ICA*.
 While dictionary learning computation time is comparable to CanICA, obtained
@@ -172,3 +134,11 @@ classification tasks.
 
    The full code can be found as an example:
    :ref:`sphx_glr_auto_examples_03_connectivity_plot_compare_decomposition.py`
+
+.. seealso::
+
+   Learn how to extract fMRI data from regions created with 
+   dictionary learning with this example:
+   :ref:`sphx_glr_auto_examples_03_connectivity_plot_extract_regions_dictlearning_maps.py`
+
+

doc/index.rst

@@ -33,8 +33,8 @@
 .. |rest_parcellations| image:: auto_examples/03_connectivity/images/sphx_glr_plot_data_driven_parcellations_001.png
    :target: auto_examples/03_connectivity/plot_data_driven_parcellations.html
 
-.. |canica| image:: auto_examples/03_connectivity/images/sphx_glr_plot_canica_analysis_011.png
-   :target: auto_examples/03_connectivity/plot_canica_analysis.html
+.. |canica| image:: auto_examples/03_connectivity/images/sphx_glr_plot_compare_decomposition_011.png
+   :target: auto_examples/03_connectivity/plot_compare_decomposition.html
 
 .. |tvl1_haxby| image:: auto_examples/02_decoding/images/sphx_glr_plot_haxby_space_net_002.png
    :target: auto_examples/02_decoding/plot_haxby_space_net.html

doc/manipulating_images/masker_objects.rst

@@ -425,4 +425,4 @@ seed position is used.
 
 .. topic:: **Examples**
 
-  * :ref:`sphx_glr_auto_examples_03_connectivity_plot_adhd_spheres.py`
+  * :ref:`sphx_glr_auto_examples_03_connectivity_plot_sphere_based_connectome.py`

doc/plotting/index.rst

@@ -41,8 +41,8 @@ different heuristics to find cutting coordinates.
      :target: ../auto_examples/01_plotting/plot_demo_glass_brain_extensive.html
      :scale: 50
 
-.. |plot_connectome| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_adhd_spheres_003.png
-     :target: ../auto_examples/03_connectivity/plot_adhd_spheres.html
+.. |plot_connectome| image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_sphere_based_connectome_003.png
+     :target: ../auto_examples/03_connectivity/plot_sphere_based_connectome.html
      :scale: 50
 
 .. |plot_anat| image:: ../auto_examples/01_plotting/images/sphx_glr_plot_demo_plotting_003.png