= Dipole scanning and importing =
''Authors: Elizabeth Bock, Francois Tadel, John C Mosher''

In Brainstorm, the brain activity is typically estimated with distributed source models including thousands of dipoles, and represented as cortical maps or functional overlays on the MRI. Another commom way of representing the source activity is to consider that there is only one single dipole that is active and that can explain most of the MEG/EEG recordings.

We offer two options to estimate the position and orientation of the most significant dipole at each time point: a '''dipole scanning''' method, which selects the most significant dipole in a grid of dipoles that are already estimated, and a non-linear '''dipole fitting''' method, which searches iteratively for the dipole that explains the best the recordings. The former is described on this page, the latter in another tutorial: [[http://neuroimage.usc.edu/brainstorm/Tutorials/DipoleFitting|FieldTrip dipole fitting]].

<<TableOfContents(2,2)>>

== Dipole modeling ==
The example below uses the protocol TutorialIntroduction created in the [[http://neuroimage.usc.edu/brainstorm/Tutorials#Get_started|introduction tutorials]].

 * Select the protocol TutorialIntroduction. Go to the view "Functional data (sorted by subjects)".
 * In the imported Run01, right-click on the head model > '''Compute sources 2016''' > '''Dipole modeling''' <<BR>><<BR>> {{attachment:compute_sources.gif||height="298",width="425"}}
 * This option is not a distributed source model like the minimum norm, that inverts the head model and explain all recordings with all the sources at once. It  represents the performance of each individual dipole, ie. its capacity  to explain all the recordings at one time sample on its own.
 * At each point of the grid, '''three dipoles''' with orthogonal directions (x,y,z) are considered, just like the unconstrained minimum norm results.
 * You can display this result in the same way as the minimum norm solutions, but you have to be cautious with the interpretation of the figure. The value at each point does not indicate the current density but the ability of the corresponding dipole to explain all the recordings. The highest values indicate the best fitting dipoles. If you see two regions with high values, it doesn't mean that there are two sources but that if there was one source only, it could be located in either of these regions.
 * Open the new dipole model file for the standard condition, and go to '''100ms'''. We expect two sources to be activated (left and right auditory cortices), but we observe mostly high dipole performance only in the left hemisphere, while the distributed minimum norm solution was detecting correctly the bilateral activity. The response on the left side being much higher in amplitude than the right one, the dipoles one the left are better capable of explaining all the recordings on their own. <<BR>><<BR>> {{attachment:dipmap_100ms.gif||height="168",width="676"}}
 * For more information about the impossibility to represent multiple sources with a single dipole, you can refer to the tutorial [[http://neuroimage.usc.edu/brainstorm/Tutorials/DipoleFitting#Multiple_dipoles|FieldTrip dipole fitting]]. We will keep on working with this example to illustrate the dipole scanning process, but we need to keep in mind that it will not be able to explain our recordings properly.
 * For a more meaningful example, refer to the tutorial [[http://neuroimage.usc.edu/brainstorm/Tutorials/Epilepsy#Dipole_scanning|EEG and epilepsy]].

== Dipole scanning ==
The process '''Sources > Dipole scanning''' searches the grid of dipoles computed previously for the most significant location. The information from the three orientations (x,y,z) are combined to get the optimal orientation at the best location.

 * In Process1, select the dipole model file for the standard condition.
 * Run process '''Sources > Dipoles scanning''': Time window='''[60,100]ms'''  <<BR>><<BR>> {{attachment:process_scanning.gif||height="251",width="491"}}
 * Double-click on the file to open it. For help on how to manipulate this view, see [[http://neuroimage.usc.edu/brainstorm/Tutorials/ExploreAnatomy#MRI_in_3D|this tutorial]]. <<BR>>The processed selected the most significant dipole at each time sample  in the selected time window (60ms-100ms). <<BR>><<BR>> {{attachment:display_all.gif||height="275",width="659"}}

== Displaying dipoles [TODO] ==
We have 25 dipoles saved in this file, one per time sample between 60ms and 100ms. You can use the  Dipoles tab to display only the most significant dipoles, and change the way they are colored.

 * Filter dipoles:
  * '''Goodness of fit''': Select only the dipoles with the highest goodness of fit.
  *

You can configure the

 * '''Time''': By default all the time points  are displayed, but you can disable the option "Show all times" to  display only the dipoles at the current time.

 * Right-click ''ERF|GLSP-dipole-scan > Display on cortex''.  The ''Dipoles'' panel is now open and dipoles are displayed on the cortex.  You can now explore the results using the options in the ''Dipoles'' panel:<<BR>><<BR>>
  * Display options: these options allow for adjusting how the selected dipoles (according to the Data options) are displayed
   * '''Show max goodness''':  will show the dipole with the maximum goodness (within the constraints of the ''Data options'') at the time point selected.  If ''Show all time'' is selected, then this represents the maximum goodness over all time points.
   * '''Show all time''': plots all selected dipoles at all time points.  Unselecting this options will show only the current time point.
   * '''3D - Color dipoles according to Time''', Goodness of Fit, Z-score, Group: adjusts the colormap to reflect the measure.
 * In the Dipoles panel, select ''Show max goodness of fit'', ''Show all time'', and color the dipoles according to ''Goodness of Fit''.  You should see the following display.  Explore the panel options to familiarize yourself with the capabilities.<<BR>><<BR>>

Click on the dipole to get detailed information about its position, amplitude and significance.

[screen capture]

The various measures are computed in this way:

== Neuromag Xfit and CTF DipoleFit ==
Brainstorm can import dipoles that have been generated using external software:

'''Neuromag Source Modeling module, xfit:''' The .bdip format is described in [[attachment:bdip_format.pdf]]. For more information about xfit and the bdip format see Neuromag Software Manuals.

'''CTF DipoleFit:''' The DipoleFit software and the .dip format is described in the CTF Software Manuals.

'''To import'''

 1. Select the study where you want to import the dipole file
 1. Right click and select ‘Import dipoles’ (Figure 1)
 1. For Neuromag, you will be prompted to specify the number of subsets used for dipole fitting. '''In most cases, this will be one.''' If subsets are used, as defined in the text file $HOME/.meg_analysis/xfit_selections, then the number of subsets used needs to be input when prompted. (Figure 2)<<BR>><<BR>>

{{attachment:import.png||height="455",width="294"}} <<BR>><<BR>> Figure 1. Importing dipoles<<BR>><<BR>> {{attachment:dipoles_subsets_dialog.jpg}} <<BR>><<BR>> Figure 2. Neuromag option for channel subsets<<BR>><<BR>>

 * When displaying dipole files with multiple groups and/or subsets, the ''Loaded dipoles'' panel appears with a list of dipoles, grouped according to event (Group #1, Group#2, etc) and by channel subset, if used (Subset #1, Subset#2, etc.)
  * Select the Group(s) to plot
  * Clicking on a subset will select all Groups with that subset.  For example, selecting Subset #1 will select Group #1 (1), Group #2 (1), Group #3 (1), etc.

=== Examples ===
 * '''Example 1''' shows 5 subsets (channel groups of Left, Right, Anterior, Posterior, All Channels). When subset #2 is selected, dipoles fitted to the right channels are displayed.  In this case, ''Show all time'' is selected for the 4 Groups (events) and colored according to ''Goodness of Fit''<<BR>><<BR>>

{{attachment:subset_group_GOF.png||height="354",width="300"}}

 * '''Example 2''' shows all groups and subsets at one time point (0.3 ms), with goodness of fit greater than 80%, colored according to ''Group''.<<BR>><<BR>>

{{attachment:allgroups_allsubsets_1time.png||height="366",width="300"}}

== Additional documentation ==
 * Tutorial: [[http://neuroimage.usc.edu/brainstorm/Tutorials/Epilepsy#Dipole_scanning|EEG and epilepsy: Dipole scanning]]
 * Tutorial: [[http://neuroimage.usc.edu/brainstorm/Tutorials/DipoleFitting|Dipoles: FieldTrip dipole fitting]]
 * Tutorial: [[http://neuroimage.usc.edu/brainstorm/Tutorials/SourceEstimation|Source estimation]]

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