Merge pull request #21 from d-scanzi/master

Added brainstorm extension

docs/README.md

@@ -18,6 +18,7 @@ Reference:
   - [Installation](#installation)
   - [Configuration](#configuration)
   - [Obtaining a lead field](#obtaining-a-lead-field)
+      - [Using a leadfield generated in Brainstorm](#using-a-leadfield-generated-in-brainstorm)
   - [Picking a source location](#picking-a-source-location)
   - [Orienting a source dipole](#orienting-a-source-dipole)
   - [Defining a source activation signal](#defining-a-source-activation-signal)
@@ -44,6 +45,7 @@ Reference:
     - [Anonymous class creation function](#anonymous-class-creation-function)
     - [Connectivity benchmarking framework](#connectivity-benchmarking-framework)
     - [Simulating data with a specific signal-to-noise ratio](#simulating-data-with-a-specific-signal-to-noise-ratio)
+- [Relativity of the Units of Measure](#relativity-of-the-units-of-measure)
 - [Contact](#contact)
 - [Special thanks and acknowledgements](#special-thanks-and-acknowledgements)
 
@@ -146,7 +148,61 @@ We can inspect the channel locations in the obtained lead field and their relati
 plot_headmodel(lf);
 plot_headmodel(lf, 'style', 'boundary', 'labels', 0);
 ```
+#### Using a leadfield generated in Brainstorm
 
+Brainstorm allows you to create personalised leadfield (aka headmodels in Brainstorm). The `lf_generate_frombrainstorm` enables you to convert a leadfield generated in Brainstorm to a format usable by SEREEGA. 
+
+```matlab
+% Run with default files
+lf = lf_generate_frombrainstorm();
+```
+
+To use this function you need to provide three file paths (plus one optional) to the following files generated by Brainstorm:
+* The headmodel *mat* file generated in Brainstorm
+* The channel location *mat* file used for the generation of the headmodel in Brainstorm
+* The structural MRI *mat* file to which the electrodes have been coregistered. 
+* (Optional) the atlas file if used
+
+Description of how to obtain these files is included in the help section of `lf_generate_frombrainstorm`
+
+The current function is provided with a precomputed headmodel and associated files. For instance, if you have created a headmodel in Brainstorm from a personal MRI scan. The default model and files were obtained as follows:
+
+* *EGI HydroCel 256* channel locations already coregistered by Brainstorm to the default T1 image (next point)
+* *ICBM152 T1* image used in the default anatomy by Brainstorm
+* Surface *Headmodel* generated from the above files by applying OpenMEEG to the BEM surfaces and costraining the dipoles to the cortex surface
+* *Mindboggle 62* atlas
+
+If you have created a personal headmodel, add the required files to the path, then use:
+
+```matlab
+% Use personal files
+lf = lf_generate_frombrainstorm('chanloc', 'PATH_TO\my_chanloc.mat', 't1', 'PATH_TO\my_T1_MRI.mat', 'headmodel', 'PATH_TO\my_headmodel.mat', 'atlas', 'PATH_TO\my_atlas.mat');
+```
+Brainstorm headmodels are expressed in $\frac{V}{A-m}$. `lf_generate_frombrainstorm` automatically converts these into $\frac{\mu V}{nA-m}$ according to the following formula:
+
+$$ \frac{V}{A-m} \cdot \frac{10^6 \mu V}{V} \cdot \frac{A}{10^9 nA} = 10^{-3} \frac{10^{-3} \mu V}{nA-m} $$
+
+The conversion allows working with realistic units, which would help define and interpret the results, especially for ERPs. However, if you desire to work with the International System, you can set the *scaleUnits* argument to 0 to turn the conversion off. The help file of the function provides more details about this.
+
+```matlab
+% Use SI units (V/A-m)
+lf = lf_generate_frombrainstorm('chanloc', 'PATH_TO\my_chanloc.mat', 't1', 'PATH_TO\my_T1_MRI.mat', 'headmodel', 'PATH_TO\my_headmodel.mat', 'atlas', 'PATH_TO\my_atlas.mat', 'scaleUnits', 0);
+```
+
+Furthermore, note that this function converts the coordinate system from the *Subject-Coordinate-System* (SCS) used in Brainstorm, to the MNI system used in SEREEGA. You can tunr this 
+option off by setting the parameter `useMNI` to 0.
+
+```matlab
+% Use SI units (V/A-m)
+lf = lf_generate_frombrainstorm('chanloc', 'PATH_TO\my_chanloc.mat', 't1', 'PATH_TO\my_T1_MRI.mat', 'headmodel', 'PATH_TO\my_headmodel.mat', 'atlas', 'PATH_TO\my_atlas.mat', 'scaleUnits', 0, 'useMNI', 0);
+```
+Finally, as Brainstorm uses the SCS, the channel and dipole coordinates are expressed in meters. `lf_generate_frombrainstorm' converts these measures in mm, for consistency with the other leadfields. 
+However, if you wish to use meters, then set the parameter `useMm` to 0. Note that the electrode names will not be displayed when calling `plot_headmodel()` with measures expressed in meters. 
+
+```matlab
+% Use SI units (V/A-m)
+lf = lf_generate_frombrainstorm('chanloc', 'PATH_TO\my_chanloc.mat', 't1', 'PATH_TO\my_T1_MRI.mat', 'headmodel', 'PATH_TO\my_headmodel.mat', 'atlas', 'PATH_TO\my_atlas.mat', 'scaleUnits', 0, 'useMNI', 0, 'useMm', 0);
+```
 
 ### Picking a source location
 
@@ -773,6 +829,11 @@ data        = utl_mix_data(sigdata, noisedata, 1/3);
 
 Also note that an additional source of noise, sensor noise, can be added to generated scalp data using the `sensorNoise` argument of `generate_scalpdata`. This noise has no dependencies across channels or samples.
 
+## Relativity of the Units of Measure
+
+It is relevant to highlight that the three leadfield provided by default (NYhead, Fieldtrip, and Pediatric Head Atlas) have different units of measure. Unfortunately, although knowing the units is important to interpret the results correctly, these have not been reported in the literature. Consequently, the units of the result are relative to the leadfield employed. As a workaround, the `generate_scalpdata` function contains a *normaliseLeadfield* argument, which normalises the leadfield values. 
+
+An exception to this is the leadfield converted from Brainstorm. Brainstorm explicitly utlises the International System; thus, every leadfield generated with it is expressed in $\frac{V}{A-m}$ (for more information: https://neuroimage.usc.edu/forums/t/eeg-units/1499). The function `lf_generate_frombrainstorm` automatically converts this in $\frac{\mu V}{nA-m}$ (unless otherwise requested). This should make the results easier to interpret.
 
 ## Contact