nilearn · AlexandreAbraham · Jul 28, 2015 · Oct 14, 2014 · Oct 14, 2014 · Oct 14, 2014
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,8 @@
 *.swo
 .DS_Store
 build
+#*
+*#
 
 nilearn.egg-info/
 dist/

diff --git a/doc/decoding/decoding_simulated.rst b/doc/decoding/decoding_simulated.rst
@@ -105,4 +105,9 @@ models, a `coef_` attribute that stores the coefficients **w** estimated
    The full file to run the simulation can be found in
    :ref:`example_decoding_plot_simulated_data.py`
 
+.. seealso::
+
+   * :ref:`space_net`
+   * :ref:`searchlight`
+
 
diff --git a/doc/decoding/decoding_tutorial.rst b/doc/decoding/decoding_tutorial.rst
@@ -426,8 +426,10 @@ To visualize the results, we need to:
 
 .. seealso::
 
-   * :ref:`searchlight`
    * :ref:`decoding_simulated`
+   * :ref:`space_net`
+   * :ref:`searchlight`
+
 
 Going further with scikit-learn
 ===================================
@@ -503,3 +505,4 @@ But, be aware that this can take A WHILE...
     has very detailed explanations on a large variety of estimators and
     machine learning techniques. To become better at decoding, you need
     to study it.
+
diff --git a/doc/decoding/estimator_choice.rst b/doc/decoding/estimator_choice.rst
@@ -1,9 +1,9 @@
 
 .. _estimator_choice:
 
-============================================
+=====================================
 Choosing the right predictive model
-============================================
+=====================================
 
 This page gives a few simple considerations on the choice of an estimator.
 It is slightly oriented towards a *decoding* application, that is the
@@ -18,11 +18,11 @@ the :ref:`dedicated section of the nilearn documentation
 
 
 Predictions: regression, classification and multi-class
-========================================================
+=======================================================
 
 
 Regression
------------
+----------
 
 A regression problem is a learning task in which the variable to predict
 --that we often call ``y``-- is a continuous value, such as an age.
@@ -33,8 +33,12 @@ Encoding models [1]_ typically call for regressions.
    Naselaris et al, Encoding and decoding in fMRI, NeuroImage Encoding
    and decoding in fMRI.2011 http://www.ncbi.nlm.nih.gov/pubmed/20691790
 
+.. seealso::
+
+   * :ref:`space_net`
+
 Classification: two classes or multi-class
--------------------------------------------
+------------------------------------------
 
 A classification task consists in predicting a *class* label for each
 observation. In other words, the variable to predict is categorical.
@@ -68,8 +72,8 @@ whereas the former is linear with the number of classes.
 
 .. seealso::
 
-    `Multi-class prediction in scikit-learn's documentation
-    <http://scikit-learn.org/stable/modules/multiclass.html>`_
+    * `Multi-class prediction in scikit-learn's documentation <http://scikit-learn.org/stable/modules/multiclass.html>`_
+    * :ref:`space_net`
 
 
 **Confusion matrix** `The confusion matrix
@@ -93,7 +97,7 @@ understand the classifier's errors in a multiclass problem.
    :scale: 40
 
 Setting estimator parameters
-=============================
+============================
 
 Most estimators have parameters that can be set to optimize their
 performance. Importantly, this must be done via **nested**
@@ -124,7 +128,7 @@ CPUs.
    * The example :ref:`example_decoding_plot_haxby_grid_search.py`
 
 Different linear models
-========================
+=======================
 
 There is a wide variety of classifiers available in scikit-learn (see the
 `scikit-learn documentation on supervised learning
@@ -222,4 +226,7 @@ little guarantee on the brain maps.
    :align: left
    :scale: 70
 
+.. seealso::
+
+   * :ref:`space_net`
 
diff --git a/doc/decoding/index.rst b/doc/decoding/index.rst
@@ -24,5 +24,6 @@ predicting an output value.
    decoding_tutorial.rst
    estimator_choice.rst
    decoding_simulated.rst
+   space_net.rst
    searchlight.rst
 
diff --git a/doc/decoding/space_net.rst b/doc/decoding/space_net.rst
@@ -0,0 +1,104 @@
+.. for doctests to run, we need to define variables that are define in
+   the literal includes
+    >>> import numpy as np
+    >>> from sklearn import datasets
+    >>> iris = datasets.load_iris()
+    >>> fmri_masked  = iris.data
+    >>> target = iris.target
+    >>> session = np.ones_like(target)
+    >>> n_samples = len(target)
+
+.. _space_net:
+
+=====================================
+Multivariate decoding with SpaceNet
+=====================================
+
+The SpaceNet decoder
+--------------------
+SpaceNet implements a suite of multi-variate priors which for improved
+brain decoding. It uses priors like TV (Total Variation) `[Michel et
+al. 2011] <https://hal.inria.fr/inria-00563468/document>`_, TV-L1
+`[Baldassarre et al. 2012]
+<http://www0.cs.ucl.ac.uk/staff/M.Pontil/reading/neurosparse_prni.pdf>`_,
+`[Gramfort et al. 2013] <https://hal.inria.fr/hal-00839984>`_
+(option: penalty="tvl1"), and Graph-Net `[Hebiri et al. 2011]
+<https://hal.archives-ouvertes.fr/hal-00462882/document>`_ (known
+as GraphNet in neuroimaging `[Grosenick et al. 2013]
+<https://hal.inria.fr/hal-00839984>`_) (option:
+penalty="smooth-lasso") to regularize classification and regression
+problems in brain imaging. The result are brain maps which are both
+sparse (i.e regression coefficients are zero everywhere, except at
+predictive voxels) and structured (blobby). The superiority of TV-L1
+over methods without structured priors like the Lasso, SVM, ANOVA,
+Ridge, etc. for yielding more interpretable maps and improved
+prediction scores is now well established `[Baldassarre et al. 2012]
+<http://www0.cs.ucl.ac.uk/staff/M.Pontil/reading/neurosparse_prni.pdf>`_,
+`[Gramfort et al. 2013] <https://hal.inria.fr/hal-00839984>`_,
+`[Grosenick et al. 2013] <https://hal.inria.fr/hal-00839984>`_.
+
+
+The following table summarizes the parameter(s) used to activate a
+given penalty:
+
+- TV-L1: `penalty="tv-l1"`
+- Graph-Net: `penalty="smooth-lasso"` (this is the default prior in
+  SpaceNet)
+
+Note that TV-L1 prior leads to a hard optimization problem, and so can
+be slow to run. Under the hood, a few heuristics are used to make
+things a bit faster. These include:
+
+- Feature preprocessing, where an F-test is used to eliminate
+  non-predictive voxels, thus reducting the size of the brain mask in
+  a principled way.
+- Continuation is used along the regularization path, where the
+  solution of the optimization problem for a given value of the
+  regularization parameter `alpha` is used as initialization
+  of for next the regularization (smaller) value on the regularization
+  grid.
+
+**Implementation:** See `[Dohmatob et al. 2015 (PRNI)]
+<https://hal.inria.fr/hal-01147731>`_ and  `[Dohmatob
+et al. 2014 (PRNI)] <https://hal.inria.fr/hal-00991743>`_ for
+technical details regarding the implementation of SpaceNet.
+
+Mixed gambles
+.............
+
+.. figure:: ../auto_examples/decoding/images/plot_mixed_gambles_space_net_001.png
+   :align: right
+   :scale: 60
+
+.. figure:: ../auto_examples/decoding/images/plot_mixed_gambles_space_net_002.png
+   :scale: 60
+
+.. topic:: **Code**
+
+    The complete script can be found
+    :ref:`here <example_decoding_plot_mixed_gambles_space_net.py>`.
+
+
+Haxby
+.....
+
+.. figure:: ../auto_examples/decoding/images/plot_haxby_space_net_001.png
+   :align: right
+   :scale: 60
+
+.. figure:: ../auto_examples/decoding/images/plot_haxby_space_net_002.png
+   :scale: 60
+
+.. topic:: **Code**
+
+    The complete script can be found
+    :ref:`here <example_decoding_plot_haxby_space_net.py>`.
+
+.. seealso::
+
+     * :ref:`Age prediction on OASIS dataset with SpaceNet <example_decoding_plot_oasis_vbm_space_net.py>`.
+
+     * The `scikit-learn documentation <http://scikit-learn.org>`_
+       has very detailed explanations on a large variety of estimators and
+       machine learning techniques. To become better at decoding, you need
+       to study it.
diff --git a/doc/index.rst b/doc/index.rst
@@ -33,6 +33,9 @@
 .. |canica| image:: auto_examples/connectivity/images/plot_canica_resting_state_011.png
    :target: auto_examples/connectivity/plot_canica_resting_state.html
 
+.. |tvl1_haxby| image:: auto_examples/decoding/images/plot_haxby_space_net_002.png
+   :target: auto_examples/decoding/plot_haxby_space_net.html
+
 .. |searchlight| image:: auto_examples/decoding/images/plot_haxby_searchlight_001.png
    :target: auto_examples/decoding/plot_haxby_searchlight.html
 
@@ -65,6 +68,8 @@
 
 * |canica|
 
+* |tvl1_haxby|
+
 * |searchlight|
 
 .. raw:: html

diff --git a/doc/modules/reference.rst b/doc/modules/reference.rst
@@ -64,6 +64,8 @@ uses.
    :toctree: generated/
    :template: class.rst
 
+   SpaceNetClassifier
+   SpaceNetRegressor
    SearchLight
 
 .. _decomposition_ref:

diff --git a/examples/decoding/plot_haxby_space_net.py b/examples/decoding/plot_haxby_space_net.py
@@ -0,0 +1,62 @@
+"""
+Decoding with SpaceNet: face vs house object recognition
+=========================================================
+
+Here is a simple example of decoding with a SpaceNet prior (i.e Graph-Net,
+TV-l1, etc.), reproducing the Haxby 2001 study on a face vs house
+discrimination task.
+"""
+
+### Load Haxby dataset ########################################################
+from nilearn.datasets import fetch_haxby
+data_files = fetch_haxby()
+
+### Load Target labels ########################################################
+import numpy as np
+labels = np.recfromcsv(data_files.session_target[0], delimiter=" ")
+
+
+### Split data into train and test samples ####################################
+target = labels['labels']
+condition_mask = np.logical_or(target == "face", target == "house")
+condition_mask_train = np.logical_and(condition_mask, labels['chunks'] <= 6)
+condition_mask_test = np.logical_and(condition_mask, labels['chunks'] > 6)
+
+### make X (design matrix) and y (response variable)
+import nibabel
+from nilearn.image import index_img
+niimgs  = nibabel.load(data_files.func[0])
+X_train = index_img(niimgs, condition_mask_train)
+X_test = index_img(niimgs, condition_mask_test)
+y_train = target[condition_mask_train]
+y_test = target[condition_mask_test]
+
+
+### Loop over Graph-Net and TV-L1 penalties ####################################
+from nilearn.decoding import SpaceNetClassifier
+import matplotlib.pyplot as plt
+from nilearn.image import mean_img
+from nilearn.plotting import plot_stat_map
+background_img = mean_img(data_files.func[0])
+for penalty in ['graph-net', 'tv-l1']:
+    ### Fit model on train data and predict on test data ######################
+    decoder = SpaceNetClassifier(memory="cache", penalty=penalty)
+    decoder.fit(X_train, y_train)
+    y_pred = decoder.predict(X_test)
+    accuracy = (y_pred == y_test).mean() * 100.
+
+    ### Visualization #########################################################
+    print("Results")
+    print("=" * 80)
+    coef_img = decoder.coef_img_
+    plot_stat_map(coef_img, background_img,
+                  title="%s: accuracy %g%%" % (penalty, accuracy),
+                  cut_coords=(-34, -16), display_mode="yz")
+    coef_img.to_filename('haxby_%s_weights.nii' % penalty)
+    print("- %s %s" % (penalty, '-' * 60))
+    print("Number of train samples : %i" % condition_mask_train.sum())
+    print("Number of test samples  : %i" % condition_mask_test.sum())
+    print("Classification accuracy : %g%%" % accuracy)
+    print("_" * 80)
+
+plt.show()
diff --git a/examples/decoding/plot_mixed_gambles_space_net.py b/examples/decoding/plot_mixed_gambles_space_net.py
@@ -0,0 +1,47 @@
+"""
+SpaceNet on Jimura et al "mixed gambles" dataset.
+==================================================
+
+The segmenting power of SpaceNet is quite visible here.
+"""
+# author: DOHMATOB Elvis Dopgima,
+#         GRAMFORT Alexandre
+
+
+### Load data ################################################################
+import numpy as np
+import nibabel
+from scipy import ndimage
+from nilearn.datasets import fetch_mixed_gambles
+data = fetch_mixed_gambles(n_subjects=16)
+zmaps, object_category, mask_img = data.zmaps, data.gain, data.mask_img
+
+
+### Fit TV-L1 #################################################################
+# Here we're using the regressor object given that the task is to predict a
+# continuous variable, the gain of the gamble.
+from nilearn.decoding import SpaceNetRegressor
+decoder = SpaceNetRegressor(mask=mask_img, penalty="tv-l1",
+                            eps=1e-1,  # prefer large alphas
+                            memory="cache")
+decoder.fit(zmaps, object_category)  # fit
+
+### Visualize TV-L1 weights
+import matplotlib.pyplot as plt
+from nilearn.plotting import plot_stat_map
+plot_stat_map(decoder.coef_img_, title="tv-l1", display_mode="yz",
+              cut_coords=[20, -2])
+
+
+### Fit Graph-Net ##########################################################
+decoder = SpaceNetRegressor(mask=mask_img, penalty="graph-net",
+                            eps=1e-1,  # prefer large alphas
+                            memory="cache")
+decoder.fit(zmaps, object_category)  # fit
+
+### Visualize Graph-Net weights
+plot_stat_map(decoder.coef_img_, title="graph-net",
+              display_mode="yz", cut_coords=[20, -2])
+
+
+plt.show()