= Machine learning: Decoding / MVPA =
''Authors: Dimitrios Pantazis''', '''Seyed-Mahdi Khaligh-Razavi, Francois Tadel, ''

This tutorial illustrates how to run MEG decoding using support vector machines (SVM).

<<TableOfContents(2,2)>>

== License ==
To reference this dataset in your publications, please cite Cichy et al. (2014).

== Description of the decoding functions ==
Two decoding processes are available in Brainstorm:

 * Decoding > Classification with SVD
 * Decoding > Classification with max-correlation classifier

These two processes work in a similar way, but they use a different classifier, so only SVD is demonstrated here.

 * '''Input''': the input is the channel data  from two conditions (e.g. condA and condB) across time. Number of  samples per condition do not have to be the same for both condA and condB, but each of them should have enough samples to create k-folds (see parameter below).
 * '''Output''': the output is a decoding time course, or a temporal generalization matrix (train time x test time).
 * '''Classifier''': Two methods are offered for the classification of MEG recordings across time: support vector machine (SVM) and max-correlation classifier.

In  the context of this tutorial, we have two condition types: faces, and  objects. We want to decode faces vs. objects using 306 MEG channels.

== Download and installation ==
 * From the [[http://neuroimage.usc.edu/bst/download.php|Download]] page of this website, download the file: '''subj04NN_sess01-0_tsss.fif'''

 * Start Brainstorm (Matlab scripts or stand-alone version).
 * Select the menu File > Create new protocol. Name it "'''TutorialDecoding'''" and select the options:

  * "'''Yes, use protocol's default anatomy'''",
  * "'''No, use one channel file per condition'''". <<BR>><<BR>> {{attachment:1_create_new_protocol.jpg||width="370"}}
  * {{attachment:decoding_protocol.gif||height="370",width="344"}}

== Import the recordings ==
 * Go to the "functional data" view (sorted by subjects).
 * Right-click on the TutorialDecoding folder > New subject > '''Subject01''' <<BR>>Leave the default options you defined for the protocol.
 * Right click on the subject node (Subject01) > '''Review raw file'''''.'' <<BR>>Select the file format: "'''MEG/EEG: Neuromag FIFF (*.fif)'''"<<BR>>Select the file: sample_decoding/'''mem6-0_tsss_mc.fif''' <<BR>><<BR>> {{attachment:decoding_link.gif||height="169",width="547"}}
 * Select "Event channels" to read the triggers from the stimulus channel. <<BR>><<BR>> {{attachment:decoding_events.gif||height="162",width="289"}}
 * We will not pay much attention to MEG/MRI registration because we are not going to compute any source models, the decoding is done on the sensor data.
 * Right-click on the "Link to raw file" > '''Import in database'''. <<BR>><<BR>> {{attachment:decoding_import.gif||height="317",width="571"}}

  * Select only two events: 201 (faces) and 203(scenes)
  * Epoch time: [-100, 1000] ms
  * Remove DC offset: Time range: [-100, 0] ms
  * Do not create separate folders for each event type
 * You will get a message saying "some epochs are shorter than the others". Answer '''yes'''.

== Select files ==
Select the Process2 tab at the bottom of the Brainstorm window.

 * Drag and drop '''40 files''' from group '''201''' to the left (Files A).
 * Drag and drop '''40 files''' from group '''203''' to the right (Files B).
 * You can select more than 40 or less. The important thing is that both ‘A’ and ‘B’ should have the same number of files. <<BR>><<BR>> {{attachment:decoding_selectfiles.gif||height="369",width="398"}}

== Cross-validation ==
'''Cross'''-'''validation''' is a model '''validation''' technique for assessing how the results of our decoding analysis will generalize to an independent data set.

 * Select process "'''Decoding > Classification with cross-validation'''": <<BR>><<BR>> {{attachment:cv_process.gif||height="388",width="346"}}

  * '''Low-pass cutoff frequency''': If set, it will apply a low-pass filter to all the input recordings.
  * '''Matlab SVM/LDA''': Require Matlab's Statistics and Machine Learning Toolbox. <<BR>>These methods do a k-fold stratified  cross-validation for you, meaning that each fold will contain the same  proportions of the two types of class labels (option "Number of folds").
  * '''LibSVM''': Requires the LibSVM toolbox ([[http://www.csie.ntu.edu.tw/~cjlin/libsvm/#download|download]] and add to your path).<<BR>>The LibSVM cross-validation may be faster but will not be stratified.

 * The process will take some time. The results are then saved in a file in the new decoding folder. <<BR>><<BR>> {{attachment:cv_file.gif||height="167",width="268"}}
 * If you double click on it you will see a decoding curve across time. <<BR>><<BR>> {{attachment:cv_plot.gif||height="172",width="355"}}

== Permutation ==
This is an iterative procedure. The training and test data for the SVM/LDA classifier are selected in each iteration by randomly permuting the samples and grouping them into bins of size n (you can select the trial bin sizes). In each iteration two samples (one from each condition) are left out for test. The rest of the data are used to train the classifier with.

 * Select process "'''Decoding > Classification with cross-validation'''". Set options as below: <<BR>><<BR>> {{attachment:perm_process.gif||height="366",width="311"}}
 * '''Trial bin size''': If greater than 1, the training data will be randomly grouped into bins of the size you determine here. The samples within each bin are then averaged (we refer to this as sub-averaging); the classifier is then trained using the averaged samples. For example, if you have 40 faces and 40 scenes, and you set the trial bin size to 5; then for each condition you will have 8 bins each containing 5 samples. Seven bins from each condition will be used for training, and the two left-out bins (one face bin, one scene bin) will be used for testing the classifier performance.
 * The results are saved in a file in the new decoding folder. <<BR>><<BR>> {{attachment:perm_file.gif||height="142",width="284"}}
 * Right-click > Display as time series (or double click). <<BR>><<BR>> {{attachment:perm_plot.gif||height="169",width="346"}}

== Acknowledgment ==
This work was supported by the ''McGovern Institute Neurotechnology Program'' to PIs: Aude Oliva and Dimitrios Pantazis.   ''http://mcgovern.mit.edu/technology/neurotechnology-program''

== References ==
 1. Khaligh-Razavi SM, Bainbridge W, Pantazis D, Oliva A (2016)<<BR>>[[http://biorxiv.org/content/early/2016/04/22/049700.abstract|From what we perceive to what we remember: Characterizing representational dynamics of visual memorability]]. ''bioRxiv'', 049700.
 1. Cichy RM, Pantazis D, Oliva A (2014)<<BR>>[[http://www.nature.com/neuro/journal/v17/n3/full/nn.3635.html|Resolving human object recognition in space and time]], Nature Neuroscience, 17:455–462.

== Additional documentation ==
 * Forum: Decoding in source space: http://neuroimage.usc.edu/forums/showthread.php?2719

<<EmbedContent(http://neuroimage.usc.edu/bst/get_feedback.php?Tutorials/Decoding)>>