= Fitting dipoles with FieldTrip =
''Authors: Jeremy Moreau, Francois Tadel''

This tutorial introduces dipole fitting and  visualization in Brainstorm. You will need to have completed the  introduction tutorials up to "Tutorial 16: Average response" before  undertaking this tutorial. This tutorial explains how to fit dipoles to  time series within Brainstorm. If you already have computed dipole fits  using CTF DipoleFit or Neuromag XFit and would like to import them in  Brainstorm, see [[http://neuroimage.usc.edu/brainstorm/Tutorials/TutDipScan#Neuromag_Xfit_and_CTF_DipoleFit|this tutorial]].

'''Warning''':  This function does not work properly with FieldTrip versions released  between 2015-10-05 and 2016-01-15. If you are using a version released  around this time, update FieldTrip first.

<<TableOfContents(2,2)>>

== Process FieldTrip: ft_dipolefitting ==
This process wraps the FieldTrip function'' ft_dipolefitting''. For background information on the implementation of the dipole modeling see [[http://www.fieldtriptoolbox.org/tutorial/natmeg/dipolefitting|the FieldTrip dipole fitting tutorial]] or watch [[https://youtu.be/pFdCWsqPEFg|this video]].

 * First you need to you need to [[http://www.fieldtriptoolbox.org/download|download FieldTrip]] and set the path to the FieldTrip folder in your Brainstorm preferences (menu File > Edit preferences). <<BR>><<BR>> {{attachment:brainstorm_preferences.png||height="237",width="516"}}
 * Open the protocol TutorialIntroduction and switch to the "functional data" view.
 * We will be fitting dipoles to the auditory ERFs computed in the tutorial [[http://neuroimage.usc.edu/brainstorm/Tutorials/Averaging|Average response]]. In a first step, we will fit a single dipole to the peak of the M100 ERF component (100ms). <<BR>><<BR>> {{attachment:tut_dipolefitting_m100_traces.png||height="156",width="353"}}
 * Expand the imported run01 and drag the average time series "Avg: standard" into the Process1 box.

 * Run process '''Sources > FieldTrip: ft_dipolefitting''': Time window='''[100,100]ms''', Sensors='''MEG '''<<BR>><<BR>> {{attachment:process_dipolefitting.gif||height="366",width="479"}}

 * Press "Run" and wait. Check the Matlab console for the progress.

 * Once the process is done computing a new dipole file will appear in your database under the average time series on which it was computed. Before continuing to visualizing the dipoles, let's compute a second dipole around the M50 component. This time we'll fit a moving dipole over a 20ms time window around the peak of the M50.<<BR>><<BR>> {{attachment:process_dipolefitting2.gif||height="171",width="291"}}

== Process options ==
 * '''Time window: '''Time  window over which to run the dipole fit. If you want to fit a dipole to  a single time point enter the same time value in the start and end  field.
 * '''Sensor type or names: '''  Type of sensor (e.g. MEG, EEG) or comma separated list of sensor names  (e.g. MLF42) to use in the dipole fit. It is not currently possible to  select multiple sensor types at once (e.g. both MEG and EEG).
 * '''Dipole type: '''For  each time sample within the selected time window, the moving dipole  option fits a dipole with a different position and orientation, whereas  the regional dipole option fits a dipole with a different orientation  but always the same position.
 * '''Number of dipoles to fit: '''The number of dipoles that will be fit at each time point.
 * '''Initial dipole grid''':  One fitting a single dipole, the dipole fitting algorithm starts with estimating the goodness of fit of a fixed grid of dipoles, then takes the best fitting one and refines  it with an iterative dipole fitting algorithm. When fitting multiple dipoles, this initial grid search is disabled because it is not supported by the function ft_dipolefitting.
 * '''Left-right symmetry constraint:'''  Selecting this option imposes a left-right symmetry constraint when  fitting two dipoles. You may want to use this when you have a reason to  believe that bilateral activation may be occuring (e.g. because you are  delivering a stimulus bilaterally).
 * '''File tag: '''Text string that will be added at the end of the comment field of the dipole file.

== Visualizing dipole files ==
 * Double click the M100 dipole file generated in the previous section. This will open up the 3D MRI viewer. For more information on usage and basic options of the 3D MRI viewer, see [[http://neuroimage.usc.edu/brainstorm/Tutorials/ExploreAnatomy#MRI_in_3D|this tutorial]]. <<BR>><<BR>> {{attachment:dipole_files.gif||height="100",width="300"}}  {{attachment:tut_dipolefitting_m100_3d_dipolefit.png||height="255",width="327"}}

 * Dipoles are coloured according to time by default, but since we've fit a dipole to a single time point in this case this option is not very useful. Under the Dipoles tab of the main Brainstorm window look for the "Color dipoles according to" subsection, and select "Goodness of fit". Larger values represent a better fit, but note that "goodness of fit" values computed using the "FieldTrip: ft_dipolefitting" process are not equivalent to those of imported CTF DipoleFit or Neuromag XFit dipoles. FieldTrip's ''ft_dipolefitting'' function computes residual variance as its measure of goodness of fit. In Brainstorm, we plot the explained variance (i.e. 1 - residual variance).
 * Now close the current 3D MRI viewer, and double click the M50 dipole file. You'll now see a series of dipoles plotted on the 3d MRI viewer.

 * Switch between the "Time" and "Goodness of fit" options to get an idea of when the best fit occurs. You can also select the "Show max goodness of fit" option to display only the dipole with the best fit or move the "Goodness" slider to hide all dipoles with a goodness value under a selected threshold. <<BR>><<BR>> {{attachment:display_m50.gif}}

== Single dipole with multiple sources ==
In the previous two examples, we fitted one single dipole at each time point. This approach is expected to work well if we assume that there is '''one active source only''' at each time point. This is not the case here, we expect a bilateral auditory response to this binaural sitmulus. We obtained results that look meaningful (dipoles close to the auditory regions) because the response we recorded is stronger on the left side, but this approach is globally '''wrong'''. This is why we had such low goodness of fit values (~50%) while we usually do not trust a dipole that fits less than 90% of the data.

If you expect to observe '''two sources of activity simultaneously''', then you need to either fit '''two dipoles''' at the same time, or to use a distributed source model. However, there are difficult methodological problems that come with multiple dipole fitting: Do you fit first a dipole and then fit a second one to the residuals? Do you try to optimize the two dipoles at once? But then how do you write your optimization function to guarantee your fitting algorithm converges? Obtaining correct results with usually requires an accurate manual initialization of the dipoles parameters, and a lot of user supervision on the process.

Let's try to see what happens if we ask FieldTrip the FieldTrip function to fit two dipoles, to explain the activity of the left and right auditory cortices simultaneously.

 * Run the process  '''Sources > FieldTrip: ft_dipolefitting''': Time window='''[40,60]ms''', Sensors=MEG, Number of dipoles to fit: '''2''', Left-right symmertry='''No''' <<BR>><<BR>>
 *



== Merging dipole files ==
You may sometimes want to visualize multiple sets of dipoles together on the same MRI viewer. For instance, you may have fit dipoles to a series of individual epileptic spikes, and would like to see whether the dipoles form a cluster. In the context of this tutorial, we are going to merge the M50 dipole file with the M100 dipole file, so that we can see where they localise relative to each other.

 * In the main Brainstorm window, select the dipole files to merge (hold down shift and click on each dipole file). Then right-click on any one of the dipole files and select "Merge dipoles". A new dipole file will be created in your database called "Merge: 2 files". Double click it to display.
 * In addition to the "Time" and "Goodness of fit" colouring options,  you'll find that the "Group" option is useful when viewing merged dipole  files. This option colours dipoles from each of the original dipole  files in a different colour. <<BR>><<BR>> {{attachment:display_merge.gif}}



== Additional documentation ==
 * Brainstorm tutorial: [[http://neuroimage.usc.edu/brainstorm/Tutorials/Epilepsy#Dipole_fitting|EEG and epilepsy: Dipole fitting]]
 * Brainstorm tutorial: [[http://neuroimage.usc.edu/brainstorm/Tutorials/TutDipScan|Dipoles: Scanning and importing]]
 * FieldTrip reference: [[https://github.com/fieldtrip/fieldtrip/blob/master/ft_dipolefitting.m|ft_dipolefitting]]
 * FieldTrip tutorial: [[http://www.fieldtriptoolbox.org/tutorial/natmeg/dipolefitting|Dipole fitting of combined MEG/EEG data]]

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